Accessing Host Data Using Host Integrator Connector APIs

This topic discusses some of the basic concepts for creating client applications that interact with host applications through Verastream Host Integrator models. You can only create client applications after you have modeled your host application using the Host Integrator Design Tool.

Host Integrator provides connectors for a variety of programming languages and environments, including Microsoft .NET, Java, COM, and C.

The first topic is relevant for all client applications:

The next three topics describe alternative approaches to interacting with data in the host application:

Note: An application that interacts with Verastream Host Integrator models should not mix model-level and table-level methods. This is because the operation definitions in these two model layers make certain assumptions about entity navigation paths and cursor positions. For example, if you issue a model-level method in a table-based model, it can break the table operations because the model subsequently can't locate the table's home entity. Unless you are very familiar with a model, you should avoid mixing procedures with direct model access.

Connecting to a Host Integrator Server

You must select one of four methods for connecting to a host integrator model:

Connecting to Models vs. Connecting to Session Pools

Your Host Integrator implementation may or may not use session pools. The key difference is that host application models do not connect to and log onto a host until you request the model; sessions are typically already connected to the host and are queued to a particular screen in a host application. So for performance reasons, connecting to a session is recommended.

Secure Connections

Verastream Host Integrator connectors communicate with Host Integrator Servers using a secure connection if the server is configured to require that communications be secure or if the client requests a secure connection by calling the RequireSecureConnection method before establishing a connection.

Accessing Host Data Using Procedures

While using model-level methods requires some knowledge of the host application model, using procedure-level methods to access table definitions of data requires no direct knowledge of the host application or the modeling process. The person who created the host application model will have abstracted the host application data into tables that can respond to SQL queries just like an actual relational database. The table interface supports a subset of the SQL 92 standard for SELECT, UPDATE, INSERT, and DELETE statements.

There are two key methods in each of the connectors for interacting with the host application at the procedure level:

Your experience and preference will generally dispose you to use one of these methods or the other. If you have SQL and/or database experience, you might prefer to use ExecuteSQLStatement. But the two methods are largely interchangeable. The concept is the same in either case: working at the procedure level turns your host application into a virtual database.

Not all filtering and sorting options that are available in SQL are possible when you access host data, though the constraints are likely to apply whether you use ExecuteSQLStatement or PerformTableProcedure.

All of the host navigation and interpretation is already contained in the procedure definitions in the model file. To see a list of procedures and columns stored in the model file, you can generate an XML- or HTML-based model file using the Export dialog box of the Design Tool.

See the documentation for your target API for information on the data structures you use to call ExecuteSQLStatement or PerformTableProcedure, or to manipulate the returned data.

Accessing Host Data Using Models

If you choose not to interact with the host application using procedures, use model-level methods to access host data or to navigate through a host application. Working at the model layer requires knowledge of the Design Tool's modeling process, and of the specific model you are interacting with. Information on the model's entities, operations, recordsets, and attributes can be accessed directly from the model, or from the XML- or HTML-based model file created in the Design Tool's Export dialog box.

Navigating Host Applications

You can use several different model-level methods to navigate through a host application. Use the SetCurrentEntity method to navigate directly to a host application screen, or the PerformEntityOperation method to navigate through a host application by executing an operation directly.

You can also navigate by means of a recordset that supports selection, using a record in the recordset to navigate to another entity. You can set the recordset index using SetCurrentRecordIndex to set the index to an absolute value, and MoveCurrentRecordIndex to set the index by a relative movement method (for example, ScrollHome, ScrollEnd, ScrollLineUp, ScrollLineDown, ScrollPageUp, and ScrollPageDown). You can select a record to navigate to another entity using the following methods:

Retrieving Data from the Host

The model level has methods for retrieving attributes and recordset records. The following methods provide access to data in the host application model:

The GetAttributes, NextRecord, and GetCurrentRecord methods all return a model record, whereas FetchRecords returns a recordset with 0 or more model records. The model record contains an index, which is the index of the record in the recordset; model records returned from GetAttributes have an index of -1. If the attributes or fields support terminal attributes and terminal attributes have been requested, the record will contain a terminal attributes object for each attribute or field.

Accessing Host Data at the Terminal Level

Unlike the model-level methods, using terminal methods requires an intimate knowledge of the host application since the entity definitions created in the model file are not used with terminal-level methods. Terminal-level access is the most laborious and inefficient way to access host data, and can usually be avoided with good modelling practices.

You can set host data directly using InsertStringAtOffset and InsertStringAtRowColumn, or access host functionality with PerformAidKey. You can access host data with GetStringAtOffset and GetStringAtRowColumn. You should only use terminal methods if you do not want to use the entity definitions that have been created in the model file.

Terminal methods also contain synchronization methods that wait for an event on the host application before executing. For example, WaitForCursor waits for the cursor to be in placed in a given row or column, WaitForString waits for a string to appear at the given row and column, and WaitForStringRelCursor waits for a string to appear at a screen position relative to the host application cursor.

Retrieving Terminal Attributes

Terminal attributes are host-generated properties that affect how an attribute displays in the terminal window. Terminal attributes are used to denote the importance of a field or its availability. Before you can retrieve terminal attributes from a model, you must enable them in the model. If you are unsure whether terminal attributes are enabled in your model, check with the model designer. For more information, see the Enable terminal attributes setting.

To retrieve terminal attributes from a host application model:

  1. Enable the retrieval of terminal attributes by calling the EnableTerminalAttributes method and setting the enable parameter to True.

    Important: After you enable terminal attributes, they remain enabled for the duration of the session, until you explicitly disable them. Leaving terminal attributes enabled will have an impact on performance, so after you have retrieved attributes, disable the setting until you need to retrieve attributes again.

  2. Use getAttributes or fetchRecords to obtain a ModelRecord or RecordSet object to be used by the getTerminalAttributes method.

  3. Retrieve the terminal attributes using the getTerminalAttributes method.

For example, here is a section of Java code that demonstrates this process:


	JOptionPane.showMessageDialog(null, "Current Entity: " + mySession.getCurrentEntity());
	entityName = JOptionPane.showInputDialog("Goto entity: ");

	JOptionPane.showMessageDialog(null, "Current Entity: " + mySession.getCurrentEntity());

	myModelRecord = mySession.getAttributes(null); //null specifies all attributes
	JOptionPane.showMessageDialog(null, myModelRecord.toString());

	attributeName = JOptionPane.showInputDialog("Attribute name: ");
	myTerminalAttributes = myModelRecord.getTerminalAttributes(attributeName);

	if (myTerminalAttributes.isReverse())
		JOptionPane.showMessageDialog(null, "isReverse = True");
	} else
		JOptionPane.showMessageDialog(null, "isReverse = False");

Using Filter Expressions

Many Verastream methods allow you to specify filter expressions when fetching records from a recordset. The following table illustrates the format for syntax expressions:

Condition Expressions

AND condition_expression AND condition_expression
OR condition_expression OR condition_expression
Not NOT condition_expression
Equal to value_expression = value_expression
Equal to (case insensitive) value_expression =* value_expression
Not equal to value_expression <> value_expression
Less than value_expression < value_expression
Greater than value_expression > value_expression
Less than or equal to value_expression <= value_expression
Greater than or equal to value_expression >= value_expression
( ) (multiple condition_expressions)

You can use expressions on both the left and right sides of the condition statement. Be sure to enclose string data in quotation marks.

Value Expressions

A value expression can take any of the following formats:

Filter Expression Examples

This example returns all recordset fields in the patients recordset that are not "Smith":

patients.lastname <> "Smith"

Here's an example that is exactly equivalent to the first example:

NOT (patients.lastname = "Smith")

This example returns all records in the SearchResults recordset with the field "last name" equal to "Smith" and the field "first name" equal to "Steven":

(SearchResults.LastName = "Smith") and (SearchResults.FirstName = "Steven")

This last example returns all fields in the AccountNumbers recordset greater than or equal to 10000 and less than or equal to 20000:

(AccountNumbers.Accounts >= 10000) and (AccountNumbers.Accounts <= 20000)