Model Examples

Several model examples, along with readme instructions, are included in the Development Kit installation and are located in your <VHI install directory>\examples\ModelSamples folder. Each model emulates a different host application to provide an interactive example of how the Design Tool is used to create a model. To simulate this emulation, the Design Tool is used in conjunction with the Host Emulator. Before viewing a model example, make sure that the Design Tool is open and the Host Emulator is started.

The example models demonstrate strategies for modeling block mode 3270 applications and character mode VT applications. Some particularly important or difficult areas of these models are discussed to assist you in discovering solutions that will work for your host application. While each host application is unique,these techniques will help you avoid the most common problems. Look through all the examples for ideas about what you might want to use in your model.

You can also review examples for individual methods in the Visual Basic Methods Reference online help.

The following host application models are included in your installation and, with the exception of pine, can be used with the Host Emulator:

• CCSDemo - An example of multi-column recordsets and accessing computer data.
• CICSAccts - An example of operation conditions, recordsets, and compound procedures.
• SIDemo - An examle of recordset selection and insertion.
• Purchases - An example of recordset implementation in a model.
• Pine - An example of a VT terminal host application.

Using CCSDemo

Provides a good example of multicolumn recordsets and accessing customer data.

The CCSDemo model is an example of a 3270 host application model. To access data using CCSDemo, use the following case sensitive search criteria:

• UserID: bjones
• Password: bjones
• Last name: smith
• First initial: c
• State: ri
• Account number for Carla Smith: 167439459

To access Carla Smith's customer profile in CCSDemo, follow these steps:

1. Open CCSDemo.modelx from the File menu.
2. On the Connection menu, click Connect to localhost via Telnet.
3. Select CustomerInquiryPanel from the Entity box in the Entity window.
4. Type 2 in the Selection field.
5. Type the above account number in the Account field and press Enter to display the account number.
6. Navigate to the AcctTransactions entity to view a multicolumn recordset.

Using CICSAccts

The CICSAccts model is an example of a 3270 host application model.

• After opening CICSAccts.modelx in the Design Tool, select Main from the Entity box. On the Main entity, view operation conditions such as preconditions, required attributes, and error patterns. Click the Operation tab and select an operation from the Name box to view details on any of the pre-configured operations. The Main entity is also a good example of demonstrating the difference between operations defined for use in tables and operations defined for direct model access.

• Navigate to the NameSearchResults entity to view how to define a recordset for read-only data. You may notice that even though Main and NameSearchResults are very similar screens, they have been designed separately. This is a good design strategy to prevent the recordset from having to be generated as a step within the Main entity. Differentiating these two screens makes use of the Screen properties not present check box for Pattern_2 on the Main entity.

• On the Model menu, click Tables to view the Tables dialog box. The Accounts table contains a good example of a compound procedure named CompoundNameSearch. Using compound procedures can be a good mechanism to provide access to more complete data sets that would otherwise be available in a single call. In this case, fetching details about all accounts that start with "w" would require two separate procedure requests (NameSearch followed by GetAccount). By connecting the two procedures, retrieving this information has been reduced to a single compound procedure.

To access data using CICSAccts, use the following case sensitive search criteria:

1. Navigate to the RecordAdd entity.

2. Click the Operation tab and select the FillWithValidData operation from the Name box. The attribute values to use are:

   • LastName: WILSON
   • FirstName: MARTIN
   • MiddleInitial: B
   • Title: MR
   • Phone: 9876543210
   • Address1: 1234 56TH ST.
   • Address2: HOUSTON, TX 98765
   • NumCardsIssued: 1
   • DayIssued: 01
   • MonthIssued: 01
   • YearIssued: 2001
   • Reason: N
   • CardCode: 1
   • ApprovedBy: 1

3. Navigate back to Main entity.

4. To do a name search, use "W" or "K" for the last name. "W" will provide you two screens to fetch, and "K" will fetch one screen.

Using SIDemo

The SIDemo model is an example of a 3270 host application model. This model can simulate the selection of multiple records in a recordset and the insertion of a new record into a recordset. To view examples of testing recordset selection and insertion, open the Test Recordset dialog box.

Using Purchases

The Purchases model is an example of a 3270 host application model. This model can simulate the updating of a current record in a recordset. Review an example using Purchases. To view other examples of testing recordsets, open the Recordset Test dialog box.

Using Pine

The Pine model is an example of a VT host application model but includes several features that could also be applied to a 3270 host application model.

To open the pine model:

1. On the File menu, click Open and select pine.modelx from the Models\pine folder.
2. On the Connection menu, click Offline mode.

The Pine Model demonstrates the Design Tool capabilities discussed below. When you work with VT models, it is critical that you take host synchronization into account.

Cursor movement

This model demonstrates the Design Tool's ability to override the cursor movement of a character mode host. By default, the Host Integrator calculates and issues the correct number of arrow key commands to change the cursor position, but many character mode hosts do not respond to this behavior. In this version of Pine, issuing arrow keys in the default manner did move the cursor, but the peculiarities of the host application caused the cursor to be moved to the wrong location. The up and down arrows are actually sufficient to change fields, so the model designer who created pine decided to override the default mechanism. See the Cursor tab on the AddAddress and UpdateAddress entities.

Another common issue with character mode hosts is tabstops. For example, issuing a move cursor command may cause the host to move the cursor first to a status line to update the text, and then to its desired location. By default, Host Integrator will issue a move cursor command and then wait for the cursor to change position. If the scanning mechanism sees the cursor in the status line, Host Integrator will assume the status line location is the new position and issue another move command in an attempt to reach the desired location. This is a good example of how the Host Integrator might get ahead of the host. For a screen defined as an entity, you can get around this by defining tabstops. These constitute all the valid "at rest" positions for the cursor on that screen; therefore, if tabstops are defined, Host Integrator will wait for the cursor to appear in one of these locations after issuing a move cursor command and before evaluating whether the desired location has been reached. The Pine model uses the location of writable attributes as tabstops.

Command lists

On the Model menu, click Properties to open the Model Properties dialog box to view the login and logout command lists created for Pine model. Command lists can help bypass the many host prompts encountered in the login sequence before actually getting to the host application. The command list is generic for any user based on WriteVarToTerminal. An API connector can set model variables with the correct userid and password at session connect, and those values would in turn be used by the login command list using the WriteVarToTerminal command.

AddressBook entity and host synchronization

The AddressBook entity demonstrates some techniques, such as including scrolling operations and setting termination conditions, to keep recordsets synchronized with the host. You can create scrolling operations that use the TransmitTerminalKey command assigned to the keystroke from which you expect to elicit a host response and then make Host Integrator wait for the host to respond with something other than a character echo. You can also verify the host response with one or more Host Events commands. For examples of scrolling operations, see the LineUp, LineDown, PageUp and PageDown operations defined on the AddressBook entity. Failure to wait would result in API calls, such as SelectRecordByFilter, executing the selection operation while the host is still trying to highlight the desired record, which may cause fetches or updates to access the wrong entry. Search for "SelectRecordByFilter" in the Host Integrator API Reference for more information.

In addition, the termination conditions for filtering the last screen allow Host Integrator to accurately detect the end of a recordset. By limiting it to non-blank records, Host Integrator correctly identifies the last record on the screen and remains synchronized with the host. Omitting this property causes Host Integrator to treat all entries as records. After a fetch call, Host Integrator assumes the host is at the bottom position of the screen instead of at the last non-blank record. Keeping the current record in line with the host is critical for character mode applications or any other recordsets that require line up and line down operations.