Interface IHostSession

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

Namespace: Attachmate.Verastream.HostIntegrator.ScriptAPI
Assembly: Attachmate.Verastream.HostIntegrator.ScriptAPI.dll
Syntax
public interface IHostSession

Properties

AttributeAtCursor

Gets the name of the attribute at the current cursor position.

Declaration
string AttributeAtCursor { get; }
Property Value
Type Description
string

the attribute name
Remarks

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.

Exceptions
Type Condition
ApptrieveException

CurrentRecord

Fetches the current record in the current recordset.

Declaration
IModelRecord CurrentRecord { get; }
Property Value
Type Description
IModelRecord

the current record or null if there is no current record
Exceptions
Type Condition
ApptrieveException

CursorPosition

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

Declaration
CursorPosition CursorPosition { get; }
Property Value
Type Description
CursorPosition

the cursor position
Exceptions
Type Condition
ApptrieveException

HomeEntity

Gets the name of the home entity for the model.

Declaration
string HomeEntity { get; }
Property Value
Type Description
string

the name of the home entity
Exceptions
Type Condition
ApptrieveException

ModelEntities

Gets the names of all entities in the model.

Declaration
IList<string> ModelEntities { get; }
Property Value
Type Description
IList<string>

a list of entity names
Exceptions
Type Condition
ApptrieveException

ModelVariableNames

Gets the names of all variables in the model.

Declaration
IList<string> ModelVariableNames { get; }
Property Value
Type Description
IList<string>

a list of variable names
Exceptions
Type Condition
ApptrieveException

TableNames

Gets the names of all tables in the model.

Declaration
IList<string> TableNames { get; }
Property Value
Type Description
IList<string>

a list of table names
Exceptions
Type Condition
ApptrieveException

TerminalScreen

Gets the size and contents of the terminal screen.

Declaration
IRectangularTerminalRegion TerminalScreen { get; }
Property Value
Type Description
IRectangularTerminalRegion

the contents of the entire terminal screen
Remarks

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

Exceptions
Type Condition
ApptrieveException

TerminalScreenSize

Gets the size of the terminal screen without the contents.

Declaration
ScreenSize TerminalScreenSize { get; }
Property Value
Type Description
ScreenSize

the height and width of the terminal screen in characters
Exceptions
Type Condition
ApptrieveException

Methods

CheckOperationConditions()

Verifies that operation conditions, as defined in the model, are satisfied.

Declaration
void CheckOperationConditions()
Remarks

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.

Exceptions
Type Condition
ApptrieveException

DefaultValue(string, string, ContextType)

Transmits a value to an attribute when unmodified.

Declaration
void DefaultValue(string attribute, string valueStr, ContextType context)
Parameters
Type Name Description
string attribute

name of attribute to be modified
string valueStr

the value to be transmitted
ContextType context

selects when the command will be executed:

Remarks

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 WriteAttribute(IWriteAttributeEvent) event handler assuming the model is not configured to cache attribute writes. This method will not, however, trigger the WriteAttributes(IWriteAttributesEvent)} event handler.

This method is identical to the DefaultValue command.

Exceptions
Type Condition
ApptrieveException

ExecuteCommandList(IList<Command>)

Executes the specified command list.

Declaration
void ExecuteCommandList(IList<Command> list)
Parameters
Type Name Description
IList<Command> list

the command list to execute.
Remarks

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:

IList<Command> list = new List<Command>();
list.Add(new WaitForDisplayString("prompt> ", 5, 0, -8, true));
list.Add(new Transmit("run"));

ExecuteOperation(string)

Performs an operation on the current entity.

Declaration
void ExecuteOperation(string operation)
Parameters
Type Name Description
string operation

the operation name
Remarks

Performs an operation on the current entity. This method will trigger the ExecuteOperation(IExecuteOperationEvent) event handler if defined.

Exceptions
Type Condition
ApptrieveException

ExecuteSQLStatement(string)

Executes an SQL statement on a table defined in the model.

Declaration
IProcedureRecordSet ExecuteSQLStatement(string sqlStatement)
Parameters
Type Name Description
string sqlStatement

the SQL statement to execute
Returns
Type Description
IProcedureRecordSet

the results of the query
Remarks

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.

Exceptions
Type Condition
ApptrieveException

ExecuteTableProcedure(string, string, IDictionary<string, string>, IDictionary<string, string>, bool, IList<string>, int)

Performs a procedure on a table defined in the model.

Declaration
IProcedureRecordSet ExecuteTableProcedure(string tableName, string procedureName, IDictionary<string, string> dataInputValues, IDictionary<string, string> filterValues, bool filterIsCaseSensitive, IList<string> outputColumnNames, int maxRows)
Parameters
Type Name Description
string tableName

name of the table
string procedureName

name of the procedure to perform
IDictionary<string, string> dataInputValues

set of data input column name-value pairs to use (not required for SELECT and DELETE procedures)
IDictionary<string, string> filterValues

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

true means that filter comparisons are case sensitive
IList<string> outputColumnNames

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

the maximum number of rows to return
Returns
Type Description
IProcedureRecordSet

the records retrieved for SELECT procedures, otherwise null
Remarks

Performs a procedure on a table defined in the model. This method will trigger the ExecuteProcedure(IExecuteProcedureEvent) event handler for the procedure if defined.

Exceptions
Type Condition
ApptrieveException

FetchRecords(int, IList<string>, string)

Fetches up to the maximum number of rows specified from the current recordset starting with the next record.

Declaration
IModelRecordSet FetchRecords(int maxRows, IList<string> fields, string filterExpression)
Parameters
Type Name Description
int maxRows

the maximum number of rows to fetch
IList<string> fields

list of the field names to fetch or null for all
string filterExpression

an expression that qualifies the records to fetch
Returns
Type Description
IModelRecordSet

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

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
Exceptions
Type Condition
ApptrieveException

GetAttribute(string)

Reads the specified attribute on the current entity and returns the value.

Declaration
string GetAttribute(string attribute)
Parameters
Type Name Description
string attribute

an attribute on the current entity
Returns
Type Description
string

the attribute value
Remarks

Reads the specified attribute on the current entity and returns the value. This method will trigger the ReadAttribute(IReadAttributeEvent) event handler if defined.

Exceptions
Type Condition
ApptrieveException

GetAttributeMetaData(string, string)

Gets the metadata for the specified attribute.

Declaration
IAttributeMetaData GetAttributeMetaData(string entity, string attribute)
Parameters
Type Name Description
string entity

name of the entity
string attribute

name of the attribute on the entity
Returns
Type Description
IAttributeMetaData

The metadata for the attribute
Exceptions
Type Condition
ApptrieveException

GetAttributeRegion(string)

Gets the location and contents of the specified attribute.

Declaration
ITerminalRegion GetAttributeRegion(string attribute)
Parameters
Type Name Description
string attribute

an attribute on the current entity
Returns
Type Description
ITerminalRegion

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.
Exceptions
Type Condition
ApptrieveException

GetAttributeRegions(IList<string>)

Gets the location and contents of the specified attributes.

Declaration
IDictionary<string, ITerminalRegion> GetAttributeRegions(IList<string> attributes)
Parameters
Type Name Description
IList<string> attributes

a list of attributes on the current entity
Returns
Type Description
IDictionary<string, ITerminalRegion>

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.
Exceptions
Type Condition
ApptrieveException

GetAttributes()

Reads all the attributes on the current entity and returns their values.

Declaration
IDictionary<string, string> GetAttributes()
Returns
Type Description
IDictionary<string, string>

a map of attribute names to attribute values
Remarks

Reads all the attributes on the current entity and returns their values. This method will trigger the ReadAttribute(IReadAttributeEvent) event handler for each attribute if defined.

Exceptions
Type Condition
ApptrieveException

GetAttributes(IList<string>)

Reads the specified attributes on the current entity and returns their values.

Declaration
IDictionary<string, string> GetAttributes(IList<string> attributes)
Parameters
Type Name Description
IList<string> attributes

a list of attributes on the current entity
Returns
Type Description
IDictionary<string, string>

a map of attribute names to attribute values
Remarks

Reads the specified attributes on the current entity and returns their values. This method will trigger the ReadAttribute(IReadAttributeEvent) event handler for each attribute if defined.

Exceptions
Type Condition
ApptrieveException

GetColumnMetaData(string, string)

Gets the metadata for the specified column in a table.

Declaration
IColumnMetaData GetColumnMetaData(string table, string column)
Parameters
Type Name Description
string table

name of the table
string column

name of the column in the table
Returns
Type Description
IColumnMetaData

the metadata for the column
Exceptions
Type Condition
ApptrieveException

GetCurrentEntity()

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

Declaration
string GetCurrentEntity()
Returns
Type Description
string

the name of the current entity or an empty string if none
Exceptions
Type Condition
ApptrieveException

GetCurrentRecordIndex()

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

Declaration
int GetCurrentRecordIndex()
Returns
Type Description
int

the index of the current record ApptrieveException

GetCurrentRecordSet()

Gets the name of the current recordset.

Declaration
string GetCurrentRecordSet()
Returns
Type Description
string

the name of the current recordset or an empty string if none
Exceptions
Type Condition
ApptrieveException

GetEntityAttributes(string)

Gets the names of all attributes on the specified entity.

Declaration
IList<string> GetEntityAttributes(string entity)
Parameters
Type Name Description
string entity

name of the entity
Returns
Type Description
IList<string>

a list of attribute names
Exceptions
Type Condition
ApptrieveException

GetEntityDescription(string)

Gets the description for an entity.

Declaration
string GetEntityDescription(string entity)
Parameters
Type Name Description
string entity

the name of the entity
Returns
Type Description
string

the description for the entity
Exceptions
Type Condition
ApptrieveException

GetEntityOperations(string)

Gets the names of all operations on the specified entity.

Declaration
IList<string> GetEntityOperations(string entity)
Parameters
Type Name Description
string entity

name of the entity
Returns
Type Description
IList<string>

a list of operation names
Exceptions
Type Condition
ApptrieveException

GetEntityRecordSets(string)

Gets the names of all recordsets on the specified entity.

Declaration
IList<string> GetEntityRecordSets(string entity)
Parameters
Type Name Description
string entity

name of the entity
Returns
Type Description
IList<string>

a list of recordset names
Exceptions
Type Condition
ApptrieveException

GetFieldMetaData(string, string, string)

Gets the metadata for the specified recordset field.

Declaration
IFieldMetaData GetFieldMetaData(string entity, string recordset, string field)
Parameters
Type Name Description
string entity

name of the entity
string recordset

name of the recordset on the entity
string field

name of the field on the recordset
Returns
Type Description
IFieldMetaData

the metadata for the recordset field
Exceptions
Type Condition
ApptrieveException

GetFieldRegion(string)

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

Declaration
ITerminalRegion GetFieldRegion(string field)
Parameters
Type Name Description
string field

field in the current recordset
Returns
Type Description
ITerminalRegion

the location and contents of the field in the current record
Exceptions
Type Condition
ApptrieveException

GetFieldRegions(IList<string>)

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

Declaration
IDictionary<string, ITerminalRegion> GetFieldRegions(IList<string> fields)
Parameters
Type Name Description
IList<string> fields

a list of fields in the current recordset
Returns
Type Description
IDictionary<string, ITerminalRegion>

a map of field names to TerminalRegion objects containing the location and contents of each field
Exceptions
Type Condition
ApptrieveException

GetLinearTerminalRegion(int, int)

Gets the contents of a linear region of the terminal screen.

Declaration
ILinearTerminalRegion GetLinearTerminalRegion(int offset, int length)
Parameters
Type Name Description
int offset

the zero-based offset
int length

the length
Returns
Type Description
ILinearTerminalRegion

the contents of the specified region
Remarks

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

Exceptions
Type Condition
ApptrieveException

GetModelVariable(string)

Gets the value of a model variable.

Declaration
string GetModelVariable(string variable)
Parameters
Type Name Description
string variable

the model variable name
Returns
Type Description
string

the model variable value
Remarks

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

Exceptions
Type Condition
ApptrieveException

GetModelVariables()

Gets the values of all model variables.

Declaration
IDictionary<string, string> GetModelVariables()
Returns
Type Description
IDictionary<string, string>

a map of variable names to values
Exceptions
Type Condition
ApptrieveException

GetOperationMetaData(string, string)

Gets the metadata for the specified operation.

Declaration
IOperationMetaData GetOperationMetaData(string entity, string operation)
Parameters
Type Name Description
string entity

name of the entity
string operation

name of the operation on the entity
Returns
Type Description
IOperationMetaData

the metadata for the operation
Exceptions
Type Condition
ApptrieveException

GetPatternRegion(string)

Gets the location and contents of the specified pattern.

Declaration
ITerminalRegion GetPatternRegion(string pattern)
Parameters
Type Name Description
string pattern

a pattern on the current entity
Returns
Type Description
ITerminalRegion

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

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.

Exceptions
Type Condition
ApptrieveException

GetPatternRegions(IList<string>)

Gets the location and contents of the specified patterns.

Declaration
IDictionary<string, ITerminalRegion> GetPatternRegions(IList<string> patterns)
Parameters
Type Name Description
IList<string> patterns

a list of patterns on the current entity
Returns
Type Description
IDictionary<string, ITerminalRegion>

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

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.

Exceptions
Type Condition
ApptrieveException

GetProcedureMetaData(string, string)

Gets the metadata for the specified procedure in a table.

Declaration
IProcedureMetaData GetProcedureMetaData(string table, string procedure)
Parameters
Type Name Description
string table

name of the table
string procedure

name of the procedure in the table
Returns
Type Description
IProcedureMetaData

the metadata for the procedure
Exceptions
Type Condition
ApptrieveException

GetRecordRegion(string)

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

Declaration
ITerminalRegion GetRecordRegion(string recordset)
Parameters
Type Name Description
string recordset

recordset on the current entity
Returns
Type Description
ITerminalRegion

the location and contents of the current record
Exceptions
Type Condition
ApptrieveException

GetRecordSetMetaData(string, string)

Gets the metadata for the specified recordset.

Declaration
IRecordSetMetaData GetRecordSetMetaData(string entity, string recordset)
Parameters
Type Name Description
string entity

name of the entity
string recordset

name of the recordset on the entity
Returns
Type Description
IRecordSetMetaData

the metadata for the recordset
Exceptions
Type Condition
ApptrieveException

GetRecordSetRegion(string)

Gets the location and contents of the specified recordset.

Declaration
ITerminalRegion GetRecordSetRegion(string recordset)
Parameters
Type Name Description
string recordset

a recordset on the current entity
Returns
Type Description
ITerminalRegion

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.
Exceptions
Type Condition
ApptrieveException

GetRectangularTerminalRegion(int, int, int, int)

Gets the contents of a rectangular region of the terminal screen.

Declaration
IRectangularTerminalRegion GetRectangularTerminalRegion(int topRow, int leftColumn, int numRows, int numColumns)
Parameters
Type Name Description
int topRow

the one-based screen row
int leftColumn

the one-based screen column
int numRows

the number of rows to get relative to topRow
int numColumns

the number of columns to get relative to leftColumn
Returns
Type Description
IRectangularTerminalRegion

the contents of the specified region
Remarks

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

Exceptions
Type Condition
ApptrieveException

GetStringAtCursor(int)

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

Declaration
string GetStringAtCursor(int length)
Parameters
Type Name Description
int length

the length of the string
Returns
Type Description
string

the display string
Exceptions
Type Condition
ApptrieveException

GetStringAtLocation(int, int, int, int)

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

Declaration
string GetStringAtLocation(int topRow, int leftColumn, int numRows, int numColumns)
Parameters
Type Name Description
int topRow

the starting row on the screen
int leftColumn

the starting column on the screen
int numRows

the number of rows to get relative to the starting row
int numColumns

the number of columns to get relative to the starting column
Returns
Type Description
string

the display string
Exceptions
Type Condition
ApptrieveException

GetStringAtOffset(int, int)

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

Declaration
string GetStringAtOffset(int offset, int length)
Parameters
Type Name Description
int offset

the offset from the start of the screen
int length

the length of the string
Returns
Type Description
string

the display string
Exceptions
Type Condition
ApptrieveException

GetTableColumns(string)

Gets the names of all columns in the specified table.

Declaration
IList<string> GetTableColumns(string table)
Parameters
Type Name Description
string table

name of the table
Returns
Type Description
IList<string>

a list of column names
Exceptions
Type Condition
ApptrieveException

GetTableDescription(string)

Gets the description for a table.

Declaration
string GetTableDescription(string table)
Parameters
Type Name Description
string table

of the table
Returns
Type Description
string

the description for the table
Exceptions
Type Condition
ApptrieveException

GetTableProcedures(string)

Gets the names of all procedures in the specified table.

Declaration
IList<string> GetTableProcedures(string table)
Parameters
Type Name Description
string table

name of the table
Returns
Type Description
IList<string>

a list of procedure names
Exceptions
Type Condition
ApptrieveException

GetVariableMetaData(string)

Gets the metadata for the specified variable.

Declaration
IVariableMetaData GetVariableMetaData(string variable)
Parameters
Type Name Description
string variable

name of the variable
Returns
Type Description
IVariableMetaData

the metadata for the variable
Exceptions
Type Condition
ApptrieveException

InsertRecord(IDictionary<string, string>)

Inserts a record into the current recordset.

Declaration
void InsertRecord(IDictionary<string, string> record)
Parameters
Type Name Description
IDictionary<string, string> record

a map of field names to values
Remarks

Inserts a record into the current recordset. This method will trigger the InsertRecord(IInsertRecordEvent) event handler if defined, otherwise the model-defined insertion method will be used.

Exceptions
Type Condition
ApptrieveException

InsertRecords(IList<IDictionary<string, string>>)

Inserts multiple records into the current recordset.

Declaration
void InsertRecords(IList<IDictionary<string, string>> records)
Parameters
Type Name Description
IList<IDictionary<string, string>> records

a list of maps, one for each record to insert into the entity. Each map should contain a set of field name and value pairs.
Remarks

Inserts multiple records into the current recordset. This method will trigger the InsertRecord(IInsertRecordEvent) event handler for each record if defined, otherwise the model-defined insertion method will be used.

Exceptions
Type Condition
ApptrieveException

MoveCurrentRecordIndex(ScrollMovement)

Moves the current record index to a new position in the current recordset.

Declaration
void MoveCurrentRecordIndex(ScrollMovement movement)
Parameters
Type Name Description
ScrollMovement movement

the type of movement to perform
Remarks

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

  • ScrollMovement.ScrollHome
  • ScrollMovement.ScrollEnd
  • ScrollMovement.ScrollLineUp
  • ScrollMovement.ScrollLineDown
  • ScrollMovement.ScrollPageUp
  • ScrollMovement.ScrollPageDown
Exceptions
Type Condition
ApptrieveException

MoveCursor(int, int)

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

Declaration
void MoveCursor(int row, int column)
Parameters
Type Name Description
int row

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

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

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

This method is identical to the MoveCursor command.

Exceptions
Type Condition
ApptrieveException

Navigate(string)

Equivalent to calling the SetCurrentEntity(string) method.

Declaration
void Navigate(string entity)
Parameters
Type Name Description
string entity

name of the entity
Remarks

Equivalent to calling the SetCurrentEntity(string) method.

This method is identical to the Navigate command.

Exceptions
Type Condition
ApptrieveException

NextRecord(string)

Finds and return a record in the current recordset using a filter expression starting with the record following the current record.

Declaration
IModelRecord NextRecord(string filterExpression)
Parameters
Type Name Description
string filterExpression

an expression that qualifies the record to find
Returns
Type Description
IModelRecord

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

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, IList<string>, string) for filter expression syntax.

ReadFromMappedAttribute(string)

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

Declaration
void ReadFromMappedAttribute(string attribute)
Parameters
Type Name Description
string attribute

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

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.

Exceptions
Type Condition
ApptrieveException

ReadVariableFromAttribute(string, string)

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

Declaration
void ReadVariableFromAttribute(string attribute, string variable)
Parameters
Type Name Description
string attribute

name of attribute on current entity to be read
string variable

name of variable to be updated
Remarks

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

This method is identical to the ReadVarFromAttr command.

Exceptions
Type Condition
ApptrieveException

ReadVariableFromField(string, string, string)

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

Declaration
void ReadVariableFromField(string recordset, string field, string variable)
Parameters
Type Name Description
string recordset

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

name of field to be read
string variable

name of variable to be updated
Remarks

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

This method is identical to the ReadVarFromRecordSetField command.

Exceptions
Type Condition
ApptrieveException

ReadVariableFromLocation(string, int, int, int)

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

Declaration
void ReadVariableFromLocation(string variable, int row, int column, int length)
Parameters
Type Name Description
string variable

name of variable to be updated
int row

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

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

the number of characters to be read
Remarks

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

This method is identical to the ReadVarFromLocation command.

Exceptions
Type Condition
ApptrieveException

ReadVariableFromTerminal(string, int)

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

Declaration
void ReadVariableFromTerminal(string variable, int length)
Parameters
Type Name Description
string variable

name of variable to be updated
int length

the number of characters to be read
Remarks

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

This method is identical to the ReadVarFromTerminal command.

Exceptions
Type Condition
ApptrieveException

ResetRecordSet(string)

Resets the state of a recordset on the current entity.

Declaration
void ResetRecordSet(string recordset)
Parameters
Type Name Description
string recordset

name of recordset to be reset
Remarks

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.

Exceptions
Type Condition
ApptrieveException

SelectCurrentRecord()

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

ApptrieveException

Declaration
void SelectCurrentRecord()

SelectRecordByFilter(string)

Finds a record in the current recordset using a filter expression and performs the model-defined selection operation.

Declaration
bool SelectRecordByFilter(string filterExpression)
Parameters
Type Name Description
string filterExpression

an expression that qualifies the record to select
Returns
Type Description
bool

true if a matching record is found and the selection succeeds
Remarks

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, IList<string>, string) for filter expression syntax.

Exceptions
Type Condition
ApptrieveException

SelectRecordByIndex(int)

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

Declaration
bool SelectRecordByIndex(int index)
Parameters
Type Name Description
int index

the index of the record to select
Returns
Type Description
bool

true if the record is found and the selection succeeds
Exceptions
Type Condition
ApptrieveException

SetAttribute(string, string)

Writes a value to the specified attribute on the current entity.

Declaration
void SetAttribute(string attribute, string attrValue)
Parameters
Type Name Description
string attribute

an attribute on the current entity
string attrValue

the value to write
Remarks

Writes a value to the specified attribute on the current entity. This method will trigger the WriteAttributes(IWriteAttributesEvent) and WriteAttribute(IWriteAttributeEvent) event handlers if defined.

Exceptions
Type Condition
ApptrieveException

SetAttributeDelayed(string, string, string)

Queues a value to be written to the specified attribute on the specified entity.

Declaration
void SetAttributeDelayed(string entity, string attribute, string attrValue)
Parameters
Type Name Description
string entity

the entity name
string attribute

an attribute on the specified entity
string attrValue

the value to write
Remarks

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 WriteAttributes(IWriteAttributesEvent) and WriteAttribute(IWriteAttributeEvent) event handlers will be triggered if defined.

Exceptions
Type Condition
ApptrieveException

SetAttributes(IDictionary<string, string>)

Writes values to the specified attributes on the current entity.

Declaration
void SetAttributes(IDictionary<string, string> attributes)
Parameters
Type Name Description
IDictionary<string, string> attributes

a map of attribute names to values
Remarks

Writes values to the specified attributes on the current entity. This method will trigger the WriteAttributes(IWriteAttributesEvent) and WriteAttribute(IWriteAttributeEvent) event handlers if defined.

Exceptions
Type Condition
ApptrieveException

SetAttributesDelayed(string, IDictionary<string, string>)

Queues values to be written to the specified attributes on the specified entity.

Declaration
void SetAttributesDelayed(string entity, IDictionary<string, string> attributes)
Parameters
Type Name Description
string entity

the entity name
IDictionary<string, string> attributes

a map of attribute names to values
Remarks

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 WriteAttributes(IWriteAttributesEvent) and WriteAttribute(IWriteAttributeEvent) event handlers will be triggered if defined.

Exceptions
Type Condition
ApptrieveException

SetCurrentEntity(string)

Sets the current entity.

Declaration
void SetCurrentEntity(string entity)
Parameters
Type Name Description
string entity

name of the entity
Remarks

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

Exceptions
Type Condition
ApptrieveException

SetCurrentRecordIndex(int)

Sets the current record in the current recordset by index.

Declaration
bool SetCurrentRecordIndex(int index)
Parameters
Type Name Description
int index

the index of the record to make current or IndexValue.SYNC_TO_HOST to make the current host record current
Returns
Type Description
bool

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

SetCurrentRecordSet(string)

Sets the current recordset by name.

Declaration
void SetCurrentRecordSet(string recordSet)
Parameters
Type Name Description
string recordSet

the name of the recordset to make current
Remarks

Sets the current recordset by name. This is only needed if there is more than one recordset for the current entity.

Exceptions
Type Condition
ApptrieveException

SetModelVariable(string, string)

Sets the value of a variable.

Declaration
void SetModelVariable(string variable, string variableValue)
Parameters
Type Name Description
string variable

the model variable name
string variableValue

the model variable value
Exceptions
Type Condition
ApptrieveException

SetModelVariables(IDictionary<string, string>)

Sets the values of one or more variables.

Declaration
void SetModelVariables(IDictionary<string, string> variables)
Parameters
Type Name Description
IDictionary<string, string> variables

map of variable names to values
Exceptions
Type Condition
ApptrieveException

ShiftCursor(int, int)

Moves the cursor relative to its current position.

Declaration
void ShiftCursor(int vertical, int horizontal)
Parameters
Type Name Description
int vertical

offset of the cursor (CURRENT_ROW means the current cursor row).
int horizontal

offset of the cursor (CURRENT_COLUMN} means the current cursor column).
Remarks

Moves the cursor relative to its current position.

This method is identical to the ShiftCursor command.

Exceptions
Type Condition
ApptrieveException

Transmit(string)

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

Declaration
void Transmit(string text)
Parameters
Type Name Description
string text

the string to transmit
Remarks

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.

Exceptions
Type Condition
ApptrieveException

Transmit(string, EchoType)

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

Declaration
void Transmit(string text, EchoType echoType)
Parameters
Type Name Description
string text

the string to transmit
EchoType echoType

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

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:

This method is identical to the TransmitANSI command.

Exceptions
Type Condition
ApptrieveException

TransmitTerminalKey(AppConnAidKey)

Sends a non-alphanumeric terminal key (for example, a Program Function key or a 3270 AID key) to the host.

Declaration
void TransmitTerminalKey(AppConnAidKey key)
Parameters
Type Name Description
AppConnAidKey key

the AppConnAidKey constant for the terminal key
Remarks

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 TransmitTerminalKey(AppConnAidKey).

This method is identical to the TransmitTerminalKey command.

Exceptions
Type Condition
ApptrieveException

TransmitToAttribute(string, string)

Writes a string to an attribute on the current entity.

Declaration
void TransmitToAttribute(string attribute, string text)
Parameters
Type Name Description
string attribute

the attribute to be written
string text

the value to write
Remarks

Writes a string to an attribute on the current entity. This method will trigger the WriteAttribute(IWriteAttributeEvent) event handler assuming the model is not configured to cache attribute writes. This method will not, however, trigger the WriteAttributes(IWriteAttributesEvent) event handler.

This method is identical to the TransmitToAttr command.

Exceptions
Type Condition
ApptrieveException

TransmitToField(string, string, string)

Writes a string to a field in the current record in the current recordset.

Declaration
void TransmitToField(string recordset, string field, string text)
Parameters
Type Name Description
string recordset

the field's recordset
string field

the field in the recordset to be written
string text

the value to write
Remarks

Writes a string to a field in the current record in the current This method will trigger the WriteField(IWriteFieldEvent) event handler assuming the model is not configured to cache field writes. This method will not, however, trigger the UpdateRecord(IUpdateRecordEvent) event handler.

This method is identical to the TransmitToField command.

Exceptions
Type Condition
ApptrieveException

TransmitToLocation(string, int, int)

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

Declaration
void TransmitToLocation(string text, int row, int column)
Parameters
Type Name Description
string text

the string to transmit
int row

the row number of the starting location for insertion
int column

the column number of the starting location for insertion
Remarks

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.

Exceptions
Type Condition
ApptrieveException

TransmitToLocation(string, int, int, EchoType)

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

Declaration
void TransmitToLocation(string text, int row, int column, EchoType echoType)
Parameters
Type Name Description
string text

the string to transmit
int row

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

the column number of the starting location for insertion (CURRENT_COLUMN means the current cursor column).
EchoType 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(string, EchoType) for the list of valid echo types.
Remarks

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

This method is identical to the TransmitToLocation command.

Exceptions
Type Condition
ApptrieveException

TransmitToOffset(string, int)

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

Declaration
void TransmitToOffset(string text, int offset)
Parameters
Type Name Description
string text

the string to transmit
int offset

character from the start of the screen buffer
Remarks

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.

Exceptions
Type Condition
ApptrieveException

TransmitToOffset(string, int, EchoType)

Transmits a string to the terminal at the specified offset.

Declaration
void TransmitToOffset(string text, int offset, EchoType echoType)
Parameters
Type Name Description
string text

the string to transmit
int offset

character from the start of the screen buffer
EchoType 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(string, EchoType) for the list of valid echo types.
Remarks

Transmits a string to the terminal at the specified offset.

This method is identical to the TransmitToOffset command.

Exceptions
Type Condition
ApptrieveException

UpdateAttribute(string)

Writes the current entity's cached attribute data for the specified attribute.

Declaration
void UpdateAttribute(string attribute)
Parameters
Type Name Description
string attribute

name of the attribute to update
Remarks

Writes the current entity's cached attribute data for the specified attribute. If data is cached for the attribute, this method will trigger the WriteAttribute(IWriteAttributeEvent)event handler. This method will not, however, trigger the WriteAttributes(IWriteAttributesEvent) event handler.

This method is identical to the UpdateAttribute command.

Exceptions
Type Condition
ApptrieveException

UpdateAttributes()

Writes the current entity's cached attribute data for all attributes.

Declaration
void UpdateAttributes()
Remarks

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 WriteAttributes(IWriteAttributesEvent) event handler.

This method is identical to the UpdateAttributes command.

Exceptions
Type Condition
ApptrieveException

UpdateAttributes(ICollection<string>)

Writes the current entity's cached attribute data for the specified attributes.

Declaration
void UpdateAttributes(ICollection<string> attributes)
Parameters
Type Name Description
ICollection<string> attributes

Collection of attribute names to update
Remarks

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 WriteAttributes(IWriteAttributesEvent) event handler.

Exceptions
Type Condition
ApptrieveException

UpdateCurrentRecord(IDictionary<string, string>)

Updates the field values of the current record in the current recordset.

Declaration
void UpdateCurrentRecord(IDictionary<string, string> record)
Parameters
Type Name Description
IDictionary<string, string> record

a map of field names to values
Remarks

Updates the field values of the current record in the current recordset. This method will trigger the UpdateRecord(IUpdateRecordEvent) event handler for each record if defined, otherwise the model-defined update method will be used.

Exceptions
Type Condition
ApptrieveException

UpdateRecordByFilter(IDictionary<string, string>, string)

Finds a record in the current recordset using a filter expression and updates its field values.

Declaration
bool UpdateRecordByFilter(IDictionary<string, string> record, string filterExpression)
Parameters
Type Name Description
IDictionary<string, string> record

a map of field names to values
string filterExpression

an expression that qualifies the record to update
Returns
Type Description
bool

true if a matching record is found and the update succeeds ApptrieveException
Remarks

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 UpdateRecord(IUpdateRecordEvent) event handler for the record found, otherwise the model-defined update method will be used.

See FetchRecords(int, IList<string>, string) for filter expression syntax.

Exceptions
Type Condition
ApptrieveException

UpdateRecordByIndex(IDictionary<string, string>, int)

Updates the field values of the record at the specified index.

Declaration
bool UpdateRecordByIndex(IDictionary<string, string> record, int index)
Parameters
Type Name Description
IDictionary<string, string> record

a map of field names to values
int index

the index of the record to update
Returns
Type Description
bool

true if the record is found and the update succeeds
Remarks

Updates the field values of the record at the specified index. This method will trigger the UpdateRecord(IUpdateRecordEvent) event handler if defined, otherwise the model-defined update method will be used.

Exceptions
Type Condition
ApptrieveException

UpdateRecordSetField(string, string)

Writes the cached field data for the specified field in the recordset.

Declaration
void UpdateRecordSetField(string recordset, string field)
Parameters
Type Name Description
string recordset

name of recordset on current entity
string field

name of the field to update
Remarks

Writes the cached field data for the specified field in the recordset. If data is cached for the field, this method will trigger the WriteField(IWriteFieldEvent) event handler. This method will not, however, trigger the UpdateRecord(IUpdateRecordEvent) event handler.

This method is identical to the UpdateRecordSetField command.

Exceptions
Type Condition
ApptrieveException

UpdateRecordSetFields(string)

Writes the cached field data for all fields in the recordset.

Declaration
void UpdateRecordSetFields(string recordset)
Parameters
Type Name Description
string recordset

name of recordset on current entity
Remarks

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 UpdateRecord(IUpdateRecordEvent) event handler.

This method is identical to the UpdateRecordSetFields command.

Exceptions
Type Condition
ApptrieveException

UpdateRecordSetFields(string, ICollection<string>)

Writes the cached field data for the specified fields in the recordset.

Declaration
void UpdateRecordSetFields(string recordset, ICollection<string> fields)
Parameters
Type Name Description
string recordset

name of recordset on current entity
ICollection<string> fields

collection of attribute names to update
Remarks

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 UpdateRecord(IUpdateRecordEvent) event handler.

Exceptions
Type Condition
ApptrieveException

UpdateRecords(IDictionary<string, string>, string)

Finds records in the current recordset using a filter expression and update their field values.

Declaration
int UpdateRecords(IDictionary<string, string> record, string filterExpression)
Parameters
Type Name Description
IDictionary<string, string> record

a map of field names to values
string filterExpression

an expression that qualifies which records to update
Returns
Type Description
int

the number of records updated
Remarks

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 UpdateRecord(IUpdateRecordEvent) event handler for the record found, otherwise the model-defined update method will be used.

See FetchRecords(int, IList<string>, string) for filter expression syntax.

Exceptions
Type Condition
ApptrieveException

Wait(int)

Waits for the specified number of seconds.

Declaration
void Wait(int duration)
Parameters
Type Name Description
int duration

the amount of time to wait in seconds
Remarks

Waits for the specified number of seconds.

This method is identical to the Wait command.

Exceptions
Type Condition
ApptrieveException

WaitForCommString(string, int)

Waits until the given string is received from the host.

Declaration
void WaitForCommString(string text, int timeout)
Parameters
Type Name Description
string text

the string to wait for
int timeout

the maximum time to wait in seconds
Remarks

Waits until the given string is received from the host.

This method is identical to the WaitForCommString command.

Exceptions
Type Condition
ApptrieveException

WaitForCommString(string, int, int)

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

Declaration
void WaitForCommString(string text, int timeout, int count)
Parameters
Type Name Description
string text

the string to wait for
int timeout

the maximum time to wait in seconds
int count

the number of times the string must be found
Remarks

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

This method is identical to the WaitForCommString command.

WaitForCondition(string, string, int)

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

Declaration
void WaitForCondition(string entity, string condition, int timeout)
Parameters
Type Name Description
string entity

the name of the entity to use as the context for the expression.
string condition

the expression to wait for
int timeout

the maximum time to wait in seconds
Remarks

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

This method is identical to the WaitForCondition command.

Exceptions
Type Condition
ApptrieveException

WaitForCursorAtAttribute(string, string, int)

Waits until the cursor is positioned within an attribute.

Declaration
void WaitForCursorAtAttribute(string entity, string attribute, int timeout)
Parameters
Type Name Description
string entity

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

the name of the attribute
int timeout

the maximum time to wait in seconds
Remarks

Waits until the cursor is positioned within an attribute.

This method is identical to the WaitForCursorAtAttribute command.

Exceptions
Type Condition
ApptrieveException

WaitForCursorAtLocation(int, int, int)

Waits until the cursor is at the specified location.

Declaration
void WaitForCursorAtLocation(int row, int column, int timeout)
Parameters
Type Name Description
int row

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

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

the maximum time to wait in seconds
Remarks

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.

Exceptions
Type Condition
ApptrieveException

WaitForCursorAtRecordSetField(string, string, string, int)

Waits until the cursor is positioned within a recordset field.

Declaration
void WaitForCursorAtRecordSetField(string entity, string recordset, string field, int timeout)
Parameters
Type Name Description
string entity

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

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

the name of the field that can terminate the wait
int timeout

the maximum time to wait in seconds
Remarks

Waits until the cursor is positioned within a recordset field.

This method is identical to the WaitForCursorAtRecordSetField command.

Exceptions
Type Condition
ApptrieveException

WaitForCursorAtTerminalField(int, int, int)

Waits until the cursor is within the terminal field at the specified location.

Declaration
void WaitForCursorAtTerminalField(int row, int column, int timeout)
Parameters
Type Name Description
int row

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

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

the maximum time to wait in seconds
Remarks

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.

Exceptions
Type Condition
ApptrieveException

WaitForCursorNotAtLocation(int, int, int)

Waits until the cursor is not at the specified location.

Declaration
void WaitForCursorNotAtLocation(int row, int column, int timeout)
Parameters
Type Name Description
int row

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

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

the maximum time to wait in seconds
Remarks

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.

Exceptions
Type Condition
ApptrieveException

WaitForCursorNotAtTerminalField(int, int, int)

Waits until the cursor is not within the terminal field at the specified location.

Declaration
void WaitForCursorNotAtTerminalField(int row, int column, int timeout)
Parameters
Type Name Description
int row

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

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

the maximum time to wait in seconds
Remarks

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.

Exceptions
Type Condition
ApptrieveException

WaitForDisplayString(string, int, int, bool, int)

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

Declaration
void WaitForDisplayString(string text, int row, int column, bool relative, int timeout)
Parameters
Type Name Description
string text

the string to wait for
int row

if relative is true, offset to cursor row; if relative is false, the one-based screen row (ANY_ROW matches any row)
int column

if relative is true, offset to cursor column; if relative is false, the one-based screen column (ANY_COLUMN matches any column)
bool relative

looks for the string relative to the cursor if true
int timeout

the maximum time to wait in seconds
Remarks

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

This method is identical to the WaitForDisplayString command.

Exceptions
Type Condition
ApptrieveException

WaitForEntities(IList<string>, int)

Waits until one of the specified entities is recognized.

Declaration
string WaitForEntities(IList<string> entities, int timeout)
Parameters
Type Name Description
IList<string> entities

array of entity names for which to wait
int timeout

the maximum time to wait in seconds
Returns
Type Description
string

the name of the entity recognized
Exceptions
Type Condition
ApptrieveException

WaitForEntity(string, int)

Waits until specified entity is recognized.

Declaration
void WaitForEntity(string entity, int timeout)
Parameters
Type Name Description
string entity

the name of the entity to wait for
int timeout

the maximum time to wait in seconds
Exceptions
Type Condition
ApptrieveException

WaitForHostData(int)

Processes any pending data received from the host.

Declaration
void WaitForHostData(int timeout)
Parameters
Type Name Description
int timeout

the maximum time to wait in seconds ApptrieveException if a Host Integrator server error occurs
Remarks

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

See Also

WaitForHostSilence(int, int)

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

Declaration
void WaitForHostSilence(int duration, int timeout)
Parameters
Type Name Description
int duration

the duration in seconds that the communication must be silent before returning
int timeout

the maximum time to wait in seconds
Remarks

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

This method is identical to the WaitForHostSilence command.

Exceptions
Type Condition
ApptrieveException

WaitForKeyboardEnabled(int, int)

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

Declaration
void WaitForKeyboardEnabled(int duration, int timeout)
Parameters
Type Name Description
int duration

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

the maximum time to wait in seconds
Remarks

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

This method is identical to the WaitForKeyboardEnabled command.

Exceptions
Type Condition
ApptrieveException

WaitForMultipleEvents(string, int)

Waits until the specified sequence of event expressions are satisfied.

Declaration
void WaitForMultipleEvents(string expression, int timeout)
Parameters
Type Name Description
string expression

the expression of events to wait for
int timeout

the maximum time to wait in seconds
Remarks

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.

<p>The expression is composed of a sequence of event statements separated
by semicolons. The syntax for the expression is as follows:</p><pre>
expression:
<event_sequence>

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

event_statement:
<event_statement> OR <event_statement>
<event_statement> AND <event_statement>
<event_statement> THEN <event_statement>
NOT <event_statement>
( <event_statement> )
<event>
</pre><p>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
Attachmate.Verastream.HostIntegrator.ScriptAPI.ApptrieveException 
will be thrown.</p><p>Note that AND and OR do not imply event sequencing. Events are 
processed in the order that they are received from the host. If 
the event sequence is critical, use the THEN operator, which 
requires the expression on the left to be satisfied before the 
expression on the right is considered, or use the semicolon 
statement separator, which has a similar effect.</p><p>This method is identical to the WaitForMultipleEvents command.</p>
Exceptions
Type Condition
ApptrieveException

WaitForNewHostScreen(int)

Processes any pending data from the host.

Declaration
void WaitForNewHostScreen(int timeout)
Parameters
Type Name Description
int timeout

the maximum time to wait in seconds
Remarks

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.

Exceptions
Type Condition
ApptrieveException
See Also

WaitForUpdate(int, int, int, int, RegionType, bool, int)

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

Declaration
void WaitForUpdate(int topRow, int leftColumn, int bottomRow, int rightColumn, RegionType regionType, bool relative, int timeout)
Parameters
Type Name Description
int topRow

the top row of the region to watch
int leftColumn

the left column of the region to watch
int bottomRow

the bottom row of the region to watch
int rightColumn

the right column of the region to watch
RegionType regionType

the type of region to use: LINEAR_REGION or RECTANGULAR_REGION
bool relative

true if the region is relative to the cursor position
int timeout

the maximum time to wait in seconds
Remarks

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

This method is identical to the WaitForUpdate command.

Exceptions
Type Condition
ApptrieveException

WaitMS(int)

Waits for the specified number of milliseconds.

Declaration
void WaitMS(int duration)
Parameters
Type Name Description
int duration

the amount of time to wait in milliseconds
Remarks

Waits for the specified number of milliseconds.

This method is identical to the WaitMS command.

Exceptions
Type Condition
ApptrieveException

WriteToMappedAttribute(string)

Writes to an attribute from its mapped variable.

Declaration
void WriteToMappedAttribute(string attribute)
Parameters
Type Name Description
string attribute

name of mapped attribute to be written
Remarks

Writes to an attribute from its mapped variable. This method will trigger the WriteAttribute(IWriteAttributeEvent) event handler assuming the model is not configured to cache attribute writes. This method will not, however, trigger the WriteAttributes(IWriteAttributesEvent) event handler.

This method is identical to the WriteToMappedAttr command.

Exceptions
Type Condition
ApptrieveException

WriteVariableToAttribute(string, string)

Writes the contents of a variable to an attribute.

Declaration
void WriteVariableToAttribute(string attribute, string variable)
Parameters
Type Name Description
string attribute

name of attribute to be written to
string variable

name of variable containing value to be written
Remarks

Writes the contents of a variable to an attribute. This method will trigger the WriteAttribute(IWriteAttributeEvent) event handler assuming the model is not configured to cache attribute writes. This method will not, however, trigger the WriteAttributes(IWriteAttributesEvent) event handler.

This method is identical to the WriteVarToAttr command.

Exceptions
Type Condition
ApptrieveException

WriteVariableToField(string, string, string)

Writes the contents of a variable to a field in the current record of a recordset defined on the current entity.

Declaration
void WriteVariableToField(string recordset, string field, string variable)
Parameters
Type Name Description
string recordset

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

name of field to be written to
string variable

name of variable containing value to be written
Remarks

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 WriteField(IWriteFieldEvent) event handler assuming the model is not configured to cache field writes. This method will not, however, trigger the UpdateRecord(IUpdateRecordEvent) event handler.

This method is identical to the WriteVarToField command.

Exceptions
Type Condition
ApptrieveException

WriteVariableToLocation(string, int, int, int, bool, EchoType)

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

Declaration
void WriteVariableToLocation(string variable, int row, int column, int maxLength, bool erase, EchoType echoType)
Parameters
Type Name Description
string variable

name variable containing value to be written
int row

the row of the location to be written to
int column

the starting column of the location to be written to
int maxLength

the maximum number of characters to write
bool 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 echoType

type of wait for echo to perform. See Transmit(string, EchoType) for values.
Remarks

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

This method is identical to the WriteVarToLocation command.

Exceptions
Type Condition
ApptrieveException

WriteVariableToTerminal(string, int, bool, EchoType)

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

Declaration
void WriteVariableToTerminal(string variable, int maxLength, bool erase, EchoType echoType)
Parameters
Type Name Description
string variable

name of variable to be read.
int maxLength

the maximum number of characters to write
bool 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 echoType

type of wait for echo to perform. See Transmit(string, EchoType) for values.
Remarks

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

This method is identical to the WriteVarToTerminal command.

Exceptions
Type Condition
ApptrieveException