Terminal Window Menus

The terminal window contains all of the menu items that can be used to configure host screens that make up the model.

• File
• Edit
• Connection
• Settings
• Events
• Model
• Debug
• Window
• Help

File

On the File menu you can create a new model, open an existing model, save models and settings, as well as open Web Builder and deploy models. Some of the more advanced options available from this menu are:

• Reload model - Click Reload Model to update the current model. This option incorporates any changes that were made to the model outside of the active Design Tool.

• Deployment options

  You can set deployment options for specific hosts, sessions, variables and recordings on the Deployment Options dialog box.

• Host - The host connection settings you specify here are used when you deploy a model from the Design Tool. You can deploy a model to either a local or a single remote server. When you deploy a model from the Design Tool a deployment descriptor file (deploy_desc.xml) is created and saved in the model's deploy\design_tool folder.

• Sessions - Use the Sessions tab on the Deployment Options dialog box to indicate whether your model will use a single session or a session pool. If your model will use a session pool, this is also where you provide the pool and startup entity names.
• Variables - Use the Variables tab of the Deployment Options dialog box to include a model variable list in your deployment, exclude or include model variables, and to require the value of certain variables to be unique and/or hidden.

• Recording - Use the Recording tab of the Deployment Options dialog box to configure model debug messages recordings for deployed models. This setting is associated with the Model Debug Messages (.vmr) feature available from the Debug tab within the Design Tool.

  Note

  This option is associated with the model only when it is deployed from the Design Tool to the local server or to another single remote server. When deploying to a production server, use deployment descriptors.

• Deploy to Local or Remote Servers - Deploy to Local Server automatically deploys the current model to your local Host Integrator Server. By default, when both the Design Tool and the server are on the same machine, the Design Tool uses the same folder for models that the Host Integrator Server uses.

  You can use a Host Integrator server other than the one associated with your copy of the Design Tool. To deploy to a single remote server use the Deploy To Remote Server option. This option is limited to the same basic settings as the local server deployment; it does not include all the options available when deploying to a non-local server using the packagemodel and activatemodel commands.

• Importing - Use the Import Model Elements dialog box to bring elements of an existing model into the model you currently have open. See Importing Model Elements for instructions. You can import XML-based documentation about your model, click Import XML Model.

• Exporting - Use these options to generate XML- or HTML-based documentation about your custom model or one of the sample models provided with the Design Tool.
• To interact with model project files in a XML format, save the file as .modelx. The files generated using this process are validated using an XML schema (.xsd) and provide an accurate representation of the project files, which is not true of the XML generated for documentation purposes using this dialog box.

Edit

Use the Edit menu to copy selected text, paste the copied contents at the cursor position (row, column) of the Design Tool, and select all the text in the terminal window. Select Linear to use word processor style selection regions that wrap lines, or Rectangular to use rectangular regions. The default is Rectangular.

Connection

The Connection menu is where you connect, disconnect, configure and define your host connections. You can also start (before you connect to the host) and stop Host Emulator recordings and datastream traces.

To review host connection properties, click Connection Properties on the Connection menu. This option is available after you connect to the host using the settings specified in the New Model or Session Setup dialog box.

More information

• Configuring a Host Session

About Traces

With the Design Tool's trace feature, you can record data transmissions to and from the host. Although trace is intended primarily for diagnostic purposes, you can use the playback feature to redisplay the host's output to your screen. Playback does not redisplay the user's input.

Enter a file name for the trace in the File name box. By default the extension for trace files is .hst. Click Trace to begin the trace. To end the trace and close the file, click Connection, point to Datastream trace and click Stop trace.

Settings

On the Settings menu you can configure your display options; colors, fonts, margins and status bar text. On this menu you also can set up preferences, event handlers, and other more advanced options.

From the Display menu:

• Display Setup Options

Other Settings menu options:

• Preferences
• Event Handlers
• View Settings

Events

You can implement event handlers to extend the capabilities of your model, to represent the host user interface within a higher-level procedural (table) interface, or to extend error handling to make host application models more robust.

Use the commands on the Events menu to attach event handlers, locate libraries and source code, and change the behavior of your event handling environment.

• Attach event handlers
• New event handler
• Event handler reset

Attach event handlers

The Attach Event Handlers dialog box, available by clicking Attach from the Events menu, is used to attach an event handler to a component in your model, to create event handlers, to launch an editor for an event handler, and to view event handler properties.

Note

You can also attach event handlers while working with any individual object that supports them. For example, the Advanced Properties button for any selected entity, attribute, operation, recordset, field, or procedure provides the same options available here.

Viewing Sources

The left-hand portion of the Attach Event Handlers dialog box provides two options for viewing components that support event handling: by the model's structure, or by the types of objects that support event handlers. Any component or component group that has an event handler already attached is displayed in bold. Any specific component type that includes an attached event handler displays a yellow lightning bolt to the left.

• Structure

  The Structure tab shows a hierarchical listing (tree view) of available components for attaching event handlers. This is a convenient way to work with a set of event sources grouped by the model structure (for example, all fields on a recordset, or all attributes on an entity). When you click a component in the Structure list, the right hand portion of the dialog box shows event sources belonging to that component, as well as any currently attached event handlers. Any type that has an event handler already attached displays a yellow lightning bolt.

• Type

  Use the Type tab to work with all components that generate the same kinds of events, regardless of where they are in the model. When you click a component in the Type list, the right hand portion of the dialog box shows event sources of that type, as well as any currently attached event handlers.

Selecting Event Handler Sources

When you select an event object on the left side of this dialog box, the associated Event Sources available in the model are displayed on the right. If you have already created event handlers for this object, click the Event Handlers column to select from the list. This list always includes a <None> option; use this to remove the attachment of an event handler to an event source.

You can select more than one event source to attach or remove a handler that applies to both.

Attaching Event Handlers

After selecting or creating an event handler, click OK to attach the event handler to the event source. If you create an event handler but do not attach it to an event source or click Cancel, the event handler is still available to attach to other objects of the same type. Use standard control key selection procedures to attach multiple event sources to the same event handler. If you want to discard the changes you have made since you opened the Attach Event Handlers dialog box, click Revert.

You can also detach event handlers and remove associated files.

New event handler

Use this dialog box to generate template code for new event handlers. The template includes the basic code for the events associated with a specific event handler type. See the event handler reference for a list of event handler object types.

Adding an event handler

1. You can open the New Event Handler dialog box from several locations.

   • Click New on the Events menu. You can select among object types when you use this option. In this case, the event handler is not attached to any particular object in the model; you must then attach it using one of the options below.

   • Click the Add Event Handler button in the Attach Event Handlers dialog box or in the Advanced Properties dialog box for a specific entity, attribute, operation, recordset, recordset field, or procedure. For model events and life cycle events, click Model Event Handlers on the Model menu. With these options, the object type is already selected when you open the New Event Handler dialog box.

2. After providing a name or confirming the provided name, add any necessary description and comments. Click OK to create a Java source file template based on the handler type. The name you provide must follow Java naming conventions. You'll see an error message when you click OK if your name does not meet these requirements.

   The source file is compiled and the output is added to a JAR file used with the model (by default, vhi_model.jar in the \models\<modelname>\scripts\lib folder)

3. After creating and compiling the code, edit the event handler source code. Click Open for Editing to have the editor open automatically when the compilation is complete.

Host Integrator includes an ant script (Java) or msbuild script (.NET) that compiles source files located within the Design Tool directory structure. You can modify the ant build.xml or the msbuild script.

New event handler settings

• Java class name or C# class name

  The Class Name can be either a simple class name or a fully qualified name (prepended package name). A default name associated with the event handler type is provided. If a package name is supplied, it becomes the default package name for this model.

• Description

  Use Description to provide additional information about the event handler in the Design Tool user interface.

• Comments

  Any information entered here is included as a block comment near the top of the generated event handler source file.

• Open for editing

  Select this check box to open a source code editor for the event handler after the source code has been edited and compiled and the class file has been added to the event handler file.

Event handler reset

An event handler reset occurs when you click Reload Handlers on the Events menu and a reset is needed. This forces a complete reset of the host and client sessions in the script manager.

The Design Tool displays a Reset Needed indicator () in the status window whenever the script manager cannot respond. Some conditions that produce this indicator are:

• An event handler is stopped at a breakpoint, and the debugger has suspended all threads

• An error in the event handler code is preventing the script manager from responding

• Java: The JVM process has been terminated.

  .NET: The clscriptserver.exe process has been terminated

Click Reload Handlers on the Events menu to force a reset.

The order in which events are fired in a event handler script manager reset sequence:

1. Client Session Destroyed
2. Host Session Destroyed
3. Model Unloaded
4. Model loaded
5. Host Session Created
6. Authenticate User. Any resulting errors display in the Event Handler console.
7. Client Session Created

If a reset causes the script manager to be recreated when an existing script manager cannot be contacted, steps 1-3 are omitted.

Model

On the Model menu you can add entities, patterns, and attributes, along with many other options. On the Model menu, point to Add and select Entity, Pattern, or Attribute for your model.

• Variables
• Tables
• Event Handlers
• Host Events
• Properties
• Templates
• Record
• Repair
• Execute Login Command
• Execute Logout Command
• Update Initial Cursor Position

Tables

Use the Tables dialog box to create and modify tables and procedures for the current host application model. Depending on what is selected in the tables and procedures box, the contents of this dialog box change to reflect these views. Tables and procedures enable you to create a database abstraction of host data.

See:

• Tables Overview
• Creating Tables
• Creating Procedures
• Creating Compound Procedures

Table Properties Pane

When a table is selected in the Tables and procedures pane, you can view and configure the following properties:

Table properties	Description
Name	Specifies the name of the currently selected table.
Description	Displays a description of the currently selected table.
Columns	Click the plus sign button on the right to add a new table column or the minus sign button to delete the selected column. Then supply a Name, Data Type, Key value, and Description for each column. Table columns defined in the Tables dialog box are initially not associated with specific procedures. For step-by-step instructions on creating table columns, see Defining Table Columns.
Column properties	Set minimum and maximum values for a column; this is an optional setting.
Allow SQL SELECT statements to return a subset of columns when all columns are requested	Select this option to have Host Integrator return a partial set of data to a querying application. If you leave this check box clear, Host Integrator will return an error to a querying application if it cannot return a full set of data.

Procedure Properties Pane

When a procedure is selected in the Tables and procedures pane, you can view and set these properties:

Procedure properties	Description
Name	The name of the procedure.
Home entity	The entity where the procedure begins. If the Navigate back to starting point upon completion option is selected, the procedure will also navigate back to this entity upon completion.
Type	Specifies the procedure's type. Choose to create one of these types of procedures: Select, Update, Insert, and Delete.
Parameters	Set these parameters for the type of procedure you are creating. See Mapping Procedure Parameters.
Available for SQL queries	If this option is selected, the procedure is available for Host Integrator to fulfill SQL queries. If this option is not selected, the procedure is only available using the PerformTableProcedure method.
Navigate back to starting point upon completion	If this option is selected, the procedure returns to its home entity upon completion. This gives you greater flexibility in creating sequences of procedures, but also increases the difficulty of assuring that Host Integrator is able to navigate from where one procedure ends off to where another begins.

Compound Procedure Properties

A compound procedure is a procedure that consists of one or more SELECT subprocedures and an UPDATE or a DELETE subprocedure. A compound procedure cannot contain an INSERT procedure. By combining one or more subprocedure into a compound procedure, you can perform more than one query level task at the same time, like selecting several records and updating or deleting them. The order in which subprocedures appear in a compound procedure is the order in which they are invoked. The first subprocedure in a compound procedure must be a SELECT subprocedure.

When you select a compound procedure in the Tables and procedures pane, you can view and set these properties:

Compound procedure properties	Description
Name	The name of the compound procedure.
Description	The compound procedure's description.
Type	Specifies the compound procedure's type. The options are SELECT, UPDATE, and DELETE.
Subprocedures	The SELECT subprocedures are listed in the Select subprocedures box, and the UPDATE or DELETE subprocedure, if any, is listed in the Update/Delete procedure box. The order the subprocedures are listed is the order they are invoked when the compound procedure is run. The first subprocedure in a compound procedure must be a SELECT subprocedure. Any output parameters from a subprocedure are used as the filter or data parameters for the next listed subprocedure.
Filter parameters	Specifies which attributes are valid in incoming query requests. Only those attributes that are selected (checked) are valid. If the Req box is checked, all queries MUST contain this attribute or the Host Integrator will return an error.

Additional parameters:

The column on the right differs according to the procedure type:

• Update— The Data parameters list specifies which attributes are updated on the host during the compound procedure. Only those attributes that are selected (checked) can be updated. If the Req box is checked, all queries MUST contain this parameter or the Host Integrator will return an error.

• Select— The Output parameters list specifies where the attribute is written from during the compound procedure. The Data Source column indicates the subprocedure that includes the attribute.

• Delete— No additional information is required for this option.

Available for SQL queries

When you select this check box, you make this procedure available for the Host Integrator to use to fulfill SQL queries. If you clear this check box, this procedure will only be available using the PerformTableProcedure method.

Event Handlers

You can add, edit, or view properties of a Life Cycle or Model event handler.

• Life cycle event handlers are those that occur outside the context of a host screen.

• Model events are those that occur when a host session is active, but are not limited to a particular component such as an entity or attribute.

Adding and viewing event handlers

Use the options below to create, edit, attach, and view properties of an model event handler or a life cycle event handler.

Option	Description
	Click this button to create a new event handler for the life cycle or model. You can also select among other event handlers for the life cycle or model that have been created. The selected event handler is attached to the life cycle or model when you click OK.
	Click the Edit button to open the event handler in your default editor.
	Click the Properties button to view event handler properties.

Event handler properties

After you have created an event handler, you can review its properties.

• Handler type - The handler type of the selected event handler. All event handlers correspond to a specific object type within a model.

• Java class name - If you provide a fully qualified name (with a prepended package name) when you created the event handler, the class reflects the final (unique) portion of the name.

• Package - The package name is displayed here if you provided a fully qualified name (with a prepended package name) when you named the event handler. When you supply a package name, it is remembered as the default package name for this model.

• Description - Shows additional information about the event handler that was entered when you created the event handler.

• Events handled - This information is based on handler metadata. All events that can be handled by this type of handler are listed, along with an indication if the event is currently enabled in this handler. The Timeout column shows any nondefault event timeout for an event, as listed in the event handler metadata.

Templates

Click Templates on the Model menu or click the Templates button on the standard toolbar to open the Model Templates dialog box. Use this dialog box to create and edit command list templates that can be reused throughout the modeling process. These templates are then stored in the modelx file. For example, create a command list containing the CheckOperationConditions command, the WaitForDisplayString command, and a TransmitToAttr command that can be used on various entities. By default, CheckOperationConditions command is automatically added to each template.

Notes

Templates are stored in the model file.

To create a model template:

1. Click the Add button. By default, the name OpTemplate_0 is provided as well as a CheckOperationConditions command.
2. To change the name of the template, select it and type the new name in the Name list.
3. To create the template, click the Edit button to open the Command List Edit dialog box.
4. Create a command list using the command options and then click OK.
5. The Model Templates dialog box opens and displays the command list in the Commands box. Click OK.

To use an existing model template in your model:

1. Open the Operation Edit dialog box and click Import to open the Import dialog box.
2. Expand Template in the Command list directory tree and select a template to use. If a green dot appears in front of the template name, it is ready to use.

Record

On the Model menu, point to Record and select from the following:

• Start Recording to start manually recording commands. This option is available before you have loaded a model into the Design Tool.

• Stop Recording

  The Stop Recording dialog box allows you to specify what happens to recorded commands. When you click Save, the Design Tool automatically generates an operation using the keystrokes recognized after Start Recording was selected on the Model menu. When you click Continue, the Design Tool closes this dialog box and continues recording commands. If you click Discard, the Discard Recording dialog box appears and verifies whether or not you want to delete the recorded operation. The following options are available for defining recorded commands:

  • Save as new operation

    This option indicates that the previous keystrokes will be saved as an operation if you click Save. By default, this option is only available if the recording began and ended at defined entities.

  • Origin

    This is a read-only setting that displays the name of the entity on which the recording started.

  • Destination

    This is a read-only setting that displays the name of the entity on which the recording stopped.

  • Name

    The name of the new operation. By default, the Design Tool generates a name for your new operation. To change the name, type it in this box.

  • Save as login command list

    Select this option to save your recorded commands as a login command list.

  • Save as logout command list

    Select this option to save your recorded commands as a logout command list.

Repair

The Entity Repair dialog box allows you to repair an entity whose signature is not recognized by the Design Tool. This option will be enabled whenever the current screen is recognized as undefined.

To use the dialog box, select the entity that should correspond to the current terminal screen from the list. You will then see that entity appear in the Entity window for editing. You can use the Signature Analyzer to determine why the Design Tool does not recognize the entity and then take corrective action.

• If the entity signature still does not match after you click Apply, you will receive a warning message. If you save changes anyway, the Entity window will once again be reset to empty.
• If you find an unexpected entity is recognized by the Design Tool, you must first define a new signature property, such as a new pattern, that differentiates the current screen from the unexpected entity. The Design Tool then automatically loads the desired entity in the Entity window. If the Design Tool does not automatically load the desired entity, use this dialog box to correct the problem.

Execute Login Command

Specifies whether you want the Design Tool to execute a login command list when your model connects to a host. For instructions, see creating a login command list.

You can also enable this setting from the General tab of the Preferences Setup dialog box by selecting the Execute login commands check box. The default is No.

This option also navigates to the home entity and initiates associated event handlers.

Execute Logout Command

Specifies whether you want the Design Tool to execute a logout command list when your model disconnects from a host. For detailed instructions, see creating a logout command list.

You can also enable this setting from the General tab of the Preferences Setup dialog box by selecting the Execute logout commands check box. The default is No.

Update Initial Cursor Position

Changes the initial cursor position to the current cursor position. You can also click the Update Initial Cursor Position button on the model toolbar. View the current cursor position and the initial cursor position in the status bar in the lower left corner of the Terminal window.

If you have configured any entity properties relative to a cursor position, these property coordinates will be automatically updated. Click Apply to save your changes or click Cancel to revert your initial cursor position back to its original state.

Debug Menu

The Design Tool provides several ways to test and debug host application models. Use the options on the Debug menu to confirm that your model is operating as you expect and is ready to deploy. The log monitor is a troubleshooting utility that you can run outside of the Design Tool. See Debugging Models for descriptions of the various commands available from the Debug menu.

Window Menu

On the Windows menu, select which toolbars to display. You can also choose to display the terminal keyboard.

Help Menu

On the Help menu you can find out more about Host Integrator, including version numbers and links to Technical Support.