Modeling Tips

• Pre-Modeling Activities
• Modeling Practices
• Optimizing the Model for Deployment
• Troubleshooting Models
• Working with Character Mode Host Applications
• Synchronization Techniques
• Supporting Files

Pre-Modeling Activities

Review the host application and take advantage of host system experts to determine:

• What business function are you encapsulating?
• How many screens are required to complete the business function?
• What are the inputs and the outputs?
• Does the application ever change? How significant are these changes?
• What errors can occur? It's important to document all paths and error conditions the model might encounter. Even if some paths are of no immediate business concern, they must be recognized and handled in the model.
• If possible, consult with more than one expert user of the host application. Users of complex host applications often have different approaches and areas of expertise. Before you begin modeling, talking to diverse experts makes it likely you will end up knowing more about the application than any one user.

• Determine the number of models needed

  You cannot access more than one host application with one model. If the application you want to develop needs to access data from more than one host application, you must create two models and develop an application that can share variables, which will allow you to integrate host data from two or more Host Integrator models.

Modeling Practices

As a common practice, you should avoid using both schemes together in one model because entity navigation paths and cursor positions can become out of synch.

• If the host supports command driven navigation, use it. This can greatly reduce navigation.

• Do not model a blank entity.

  Modeling blank entities can cause undesired side effects. Some command-driven hosts use blank entities to accept commands. In these cases, you can write your commands to a blank entity as part of a command sequence without actually having it exist as an entity.

• Use tables to manipulate host application data

• There is less processing overhead using tables, because there is only one "round trip" needed to the server.

• Using SQL reduces the amount of coding necessary.

• Set naming conventions

• Determine a standard notation for entities and attributes.

• Decide how to handle duplicate attribute names; there may be several fields called account_number among the host screens.
• If using COM objects, do not use a Visual Basic reserved word as an attribute name.

• Do not use reserved SQL words to name tables.

• Determine global settings

• Set traversal operation preferences; traversal operations are usually automatically generated.

• Set entity and attribute generation preferences; these are usually created manually so you can generate only the entities and attributes that are necessary.

• Create concise operations

  Break large operations into a sequence of smaller operations, using alternate and intermediate destinations. Modeling is very like programming. Do not be in a hurry. Be careful and meticulous. It is often advantageous to work on a pair of screens at a time, the second screen being the destination of the first, and get each pair working error-free before moving to the next set. Sometimes you may have to capture a lot of screens quickly; if this is the case, import them one by one into what will become your carefully crafted model.

• Minimize patterns used to identify an entity

• Create patterns at the top and bottom of each entity to ensure the entire screen is displayed.

• Do not add more patterns than necessary as this adds to the processing time to recognize an entity.

• Parameters and Constants

• DefaultValue commands should have the Application parameter set to "Default value for server and design tool."

• When an attribute is available, all constant values should use TransmitToAttr.

• Correctly spell and set all constant values.

• Timing for 5250 Models

  When creating 5250 based models, define patterns for each of the input fields on the sign-on screen and on any screen where the timing of screen recognition is difficult because the AS/400 sends multiple writes to create the screen.

To set up input field patterns:

1. On the Pattern tab, select the Definition subtab.
2. The default definition is Text. Clear the Text check box and select the Field type check box.
3. Select Unprotected as the Field type.

By defining these patterns for the input fields, the screen recognition process waits until these fields are ready for input. This ensures proper screen recognition and enhances model performance.

Optimizing the Model for Deployment

After you have completed your model, take these steps to prepare the model for optimum performance before deploying it to Host Integrator Server.

• Delete unnecessary entities

• Include in your model only entities that contain necessary data or those that are intermediaries between entities containing this data.

• Do not create an entity for a host blank screen unless you have exhausted all other options. Blank screens have the potential of producing run-time entity signature ambiguity that could crash a session.

• Delete unnecessary or unused attributes

  To improve performance and reduce memory consumption, make sure that the attributes of each entity contain necessary data or input fields.

• Delete all unnecessary operations

  Validate the paths between entities to ensure they are traversable by the shortest route.

• Reduce the screen signature

  Review the screen signature of every entity in the model and reduce it to the minimum number of patterns required to uniquely identify the entity.

• Optimize traversal operations

  Before deploying the model, make sure the traversal operations are as efficient as possible. Open the model in off-line mode and follow these steps to review the operations for each entity:

  • Each traversal entity is named To <entity> and the destination entity matches this name.
  • Edit operations to remove the checkOperationConditions command if there are no pre or post conditions on this operation.

Troubleshooting Models

• Validate the model using Validator

• Use Web Builder to create a web client

  Use Web Builder to quickly and easily generate a Web application of the host application model. Use this application to test your model functionality.

• Test possible error conditions for each operation

  You can test possible error conditions for each operation by inputting bad data or by reproducing mainframe error conditions.

• Test the model parameters

  • Test the write attributes, recordsets, procedures, and SQL statements.
  • Every entity should be able to navigate to the home entity.
  • Make sure that all screens, including error screens, can recover themselves (that is, they can navigate to the home entity).

• Recognizing screens as entities

Invariably, your application will contain one or two screens that prove difficult to model. Problems range from unpredictable host data transmission timings to the host redrawing seemingly static portions of the screen. With these screens, it will take a little bit of extra observation and experimentation to model accurately. Evaluate the order in which the host writes the screen. Watch the behavior of the cursor. Use model debug messages to look for events that could be causing the problem.

• Synchronizing with the host

• Getting out of sync with your host is one of the most common problems encountered when modeling host applications. If your model works well in the Design Tool, but seems to malfunction in the server environment, the lack of synchronization is the most likely reason. Host sessions running on a Host Integrator server run faster than those in the Design Tool because there is no display to update. Therefore, the server can expose synchronization problems that don't appear in the Design Tool.

  This advice applies particularly to operations that scroll recordsets or perform other tasks within a single screen. Even on block mode host applications, Host Integrator will sometimes try to perform operations too quickly, producing incorrect results. See Synchronization Techniques for more information.

• Never use WaitFor (some time period) to synchronize unless there is absolutely no other alternative; 1 millisecond over and you're out of synch.

Working with Character Mode Host Applications

In character mode applications, the host is constantly moving the cursor to write data, so just waiting for the cursor to end up in the correct position after a host update may be sufficient. If the cursor is placed in varying positions but in the same place relative to some text, then a WaitFor command is recommended.

To ensure synchronization, end all operations with an appropriate WaitFor command.

Synchronization Techniques

Your host application may be unpredictable when slower execution masks missed synchronization issues. Synchronization in a Host Integrator model ensures that the entire host screen has been received before reading or transmitting data. If you don't develop methods to ensure synchronization, the model can read incorrect values from attributes and fields, write to the wrong locations, or fail to position the cursor at a desired location.

Synchronization is important in operations, when writing attributes, and when using cursor movement commands.

Implementing synchronization techniques is critical for any VT or HP character mode model, and can be important for 3270 and 5250 block mode models where the screen is received in multiple command chains. To view a model example of a VT host application, see the Pine model located in your <VHI install directory>\examples\ModelSamples folder.

There are two basic techniques for ensuring synchronization.

• You can issue Wait commands such as WaitForDisplayString, WaitForCursorAtAttribute, WaitForCursorAtField, WaitForCursorAtLocation, WaitForCommString, WaitForUpdate, WaitForKeyboardEnabled, WaitForMultipleEvents

• You can validate an entity based on patterns or cursor position.

Strategies for Synchronizing Character Mode (VT and HP)

Character mode applications require extra effort to ensure that the model is in synch with the host screen.

In general, using an appropriate Wait command to end an operation is the most reliable technique for ensuring synchronization. The wait commands below are listed with the most highly recommended strategies listed first.

• If possible, use WaitForDisplayString. This command applies to cases where the command is prompting for input.
• If not, use WaitForCommString. This command applies when there are escape sequences in the host data and the last set of escape sequences is unique.
• WaitForCursorAtLocation. This command can be used if the cursor always arrives at the same location. This command may not be dependable if the cursor passes through a location in a transition before arriving at the location a second time.
• WaitForUpdate. This command is not recommended unless you're dealing with a small update area. The first character changed in the specified region will satisfy this wait condition. If you're updating a model created with an earlier version of Host Integrator, be sure to disable the compatibility switches associated with WaitForUpdate.
• When the host response could differ from one time to the next, use a WaitForMultipleEvents command. This command allows several globally defined events to be encapsulated into one command within an operation. This enables Host Integrator to rely on an order of events rather than the number of data packets that are sent from a character mode host.

WaitForCommString Command and Nonprintable Characters

For VT and HP character mode hosts, you can wait for datastream sequences that include nonprintable characters such as carriage return, linefeed, and the escape key. These sequences can be captured by copying and pasting text from the Model Debug Messages dialog box into the Operation Edit dialog box when the WaitForCommString command is selected. An example of this syntax is "\033EnterData", which represents the escape key followed by the string data. This syntax represents the C programming language conventions that use a backslash () followed by three octal numbers to represent any character.

WaitForMultipleEvents Command

Many operations have alternate destinations; the best way to synchronize at a destination is to use the WaitForMultipleEvents command. In the example below, the first event satisfied when reaching a destination, but the second event is satisfied with a second destination.

Tips:

• Add a WaitForUpdate command to a page down operation to prevent the operation from completing until a particular location on the screen has been updated by the host.
• See the AddressBook entity in the Pine model example to view a recordset with several types of scrolling operations, including a PageDown, PageUp, LineUp, and LineDown operation.

Example:

Create global events in the Event Edit dialog box using host event commands at the end of the operation to verify that the cursor position has returned to a particular location.

1. Click the right arrow button and select New Host Screen and Cursor Enter Position. Make sure to specify the row and column coordinates.

   The first command waits for the cursor to return to a specific position, and the second command specifies a second cursor position. The following events now appear in the Events box:

   Event 1 (WaitForCursorEnterPosition Row, Col)

   Event 2 (WaitForCursorEnterPosition Row, Col)

2. Click OK.

3. Open the Operation Edit dialog box, click the right arrow button, point to Events, and select the WaitForMultipleEvents command.
4. Under Command parameters, click the Edit button to open the Event Expression Editor dialog box.
5. Select Event 1, click the And button, and select Event 2.
6. Click OK. The Operation Edit dialog box opens and displays your new WaitForMultipleEvents command in the Commands box.

    public void entityDeparture(EntityDepartureEvent event) throws ApptrieveException {
        if (event.getNextEntity().length() == 0) {
            event.overrideDeparture();
            myProcessScreenFunction(event, event.getTerminalScreen());
        }        
    }

Writing Data to the Screen

When writing data to the screen, notice the mode of the terminal. If the mode is insert, for example, you may have to issue a special command to clear a field before transmitting the data (see the Pine model for an example). If the mode is overwrite, then you may need to utilize the Erase to end of attribute setting in your attributes. Failing to do so could result in garbled data when a shorter piece of data is written over a longer one, leaving the end of the original data in place to be sent to the host.

If you are working with a character mode host, take special note of the Attribute Echo tab options related to waiting for character echo. Failing to wait for character echo can often cause subsequent operations or cursor movement to fail. The same issues apply to static transmission commands (TransmitANSI, for example) that you can utilize in operations.

Strategies for Synchronizing 3270 and 5250 Applications

Add synchronization if a block mode screen is received in multiple command chains. Your options include:

• Add a validation pattern to the entity that is recognized only when the last command chain is received
• Add a WaitForDisplayString command to the operation
• Add a WaitForUpdate command to the operation. If you're modifying a model that was created in an earlier version, be sure to disable the compatibility switches for VHI 4.5 WaitForUpdateCompatibility and VHI 5.5 WaitForUpdate 3270 and 5250.
• Add WaitForKeyboardEnabled to the operation.

Entity Validation (Validation tab of Advanced Entity Properties)

Configuring entity validation is helpful when modeling character mode applications since there is nothing in the character mode datastream to denote what constitutes a screen. In general, using the Wait options described above is recommended over using to entity validation.

On the Validation tab of the Advanced Entity Properties dialog box, use the arrival validation options to configure how to validate a certain entity. This validation enables Host Integrator to delay its entity arrival notification until certain conditions are met. Select one of the following options to configure entity validation:

• Option 1: Select the Wait for cursor check box to validate the entity once the cursor arrives at a certain position. Specify the position in the Row and Col boxes.

• Option 2: If Option 1 fails, select the Wait for patterns check box and move one or more configured patterns from the Unused list to the Check list. Once a validation pattern is moved to the Check list, Host Integrator will not validate the entity until this pattern is identified.

  • Make sure to clear the Use in entity signature check box on the Pattern tab before using a pattern for entity validation.

  • Using a pattern in entity validation isn't necessarily the best solution for modeling character mode applications because the pattern may appear while the cursor is moving around the screen. Try configuring Option 1 before trying this method.

• Option 3: Select the Wait for condition check box to create a condition in the Condition Edit dialog box. This option often handles situations where the final cursor position may be at any of several locations.

Synchronizing for Cursor Movement and Writing Attributes

When you need to synchronize cursor movement for writing attributes, use a post-write operation to position the cursor at the next attribute. The Wait commands described above work for these synchronization tasks as well.

If post-write operations don't cover cursor movement requirements, you may need to define cursor movement command lists for VT and character mode HP hosts. Cursor movement definitions are especially important when the cursor cannot be moved to a location on the screen with the arrow keys. Without a cursor movement command list, Host Integrator's default is to use the arrow keys. For example, if the cursor is at (2,2) and the attribute is at (2,10), Host Integrator sends eight right arrow keys to the host attempting to end up at the correct location. Sometimes, these host applications can be unpredictable and the cursor may not end up in the same position each time that screen is used. If Host Integrator does not reach the expected location, you will receive the error that the cursor could not be moved.

• If the host uses the Tab key to move between fields, define a global move forward cursor movement command list in the Advanced Model Properties dialog box. To be more precise about cursor movement between entities, configure the options on the Cursor tab.

• One synchronization technique when working with block mode terminals is to move the cursor before scrolling and then wait for the host to restore it to the normal initial position when it is finished.

Example using the Tab key with a VT host: TransmitTerminalKey rcVtTabKey

Example using the Return key with an HP host: TransmitTerminalKey rcHPReturnKey

In each case, the command sends the tab key or return key to move the cursor. If the host does more than move the cursor to the next location (for example, it updates a status line or redraws other sections of the screen), then you should be using tabstops. Use the Model Debug Messages option to determine if the host is doing more than just moving the cursor.

Once you've defined a move forward command list, Host Integrator will repeatedly execute this command list until it arrives at the starting location for the attribute or attributes you are writing to. If the host never positions the cursor at the attribute, you will receive an error that the cursor could not be moved.

Tabstops (Cursor Tab)

If the host sends more than one packet in response to the tab key, define tabstops on any entity that has multiple attributes. When tabstops have been defined on an entity, Host Integrator will wait for the cursor to arrive at a defined tabstop after each execution of a move forward or move backward command list.

If moving through the fields of your host application requires application interaction, you may have to define the tabstops manually. Using other techniques, such as implementing Wait commands in post-write operations, is recommended over the use of tabstops.

You can define tabstops for an entity on the Cursor tab.

Debugging Synchronization Problems

Use the Model Debug Messages debug option to review the real-time data sent and received from a host.

Supporting Files

Project directories can contain the following:

• Host information, including name and port number for a Telnet connection
• Login, logout, or move cursor command lists
• Entity definitions, including patterns, attributes, operations, recordsets, and fields
• Variables with default values
• Tables, including column and query definitions
• Model properties

In addition to creating a model or modelx file, the Design Tool also generates the following project files:

Supported files for .model file types

• Screen snapshots file (.snapshot file) contains a captured image of a defined entity, which can be viewed during offline design of the model with the Host Emulator.
• The Scripts directory Source files, JAR/assembly files, and class files associated with event handlers are stored within this folder. In particular, build.xml, the \src subfolder,and the \lib subfolder are required for event handler maintenance.
• Deployment files, located in the \deploy folder, are generated after you deploy the model to the local server.

Supported files for .modelx file types

• Modelx and modelx_1.xsd files located in the \models folder
• Entityx and entityx_1.xsd files located in the \entities folder within the modelx folder.
• Tablex and tablex_1.xsd files located in the \tables folder.
• The Scripts directory Source files, JAR/assembly files, and class files associated with event handlers are stored within this folder. In particular, build.xml, the \src subfolder,and the \lib subfolder are required for event handler maintenance.
• Deployment files, located in the \deploy folder, are generated after you deploy the model to the local server.

The .xsd files define the valid XML that can be used for modelx, entityx. and tablex files.