Adding Entities to a Model

An entity is a unique host application screen. After you label your host application screen as an entity, you must define it using entity definitions and entity properties.

To add an entity to a model:

1. When the first screen appears after connecting to the host, click the New Entity button in the Entity window. (All of the other options are unavailable at this point.)

2. By default, the entity is named Entity_1. To change the name, select it and type a new name in the Entity box.

3. Click Apply to save your changes.

4. Now, add a pattern to the entity. See Adding Patterns.

You can also copy entities as shown in Copy Entity.

Adding Patterns

A pattern is a selected area on an entity that does not contain data that changes from session to session.

To add a pattern to an entity:

1. After you've created an entity, use the cursor to select a static section of the host screen to create a pattern.

   Each pattern can have up to 259 characters.

   Tip

   You can choose to auto-generate patterns by clicking the Auto-generate button, but you will still have to assign properties and error conditions to these patterns on the Pattern tab.

2. On the Pattern tab, click the New Pattern button. All of the other options on this tab are unavailable at this point.

3. By default, the pattern is named Pattern_1. To change the name, select it and type a new name in the Name box. The Design Tool has now recorded the position, properties, and the signature parameters of the pattern.

4. Click Apply to save your changes.

5. Now, add attributes to identify text fields on the entity as shown in Adding Attributes.

To copy a pattern:

After you have created a pattern, you may need to create another that is similar. You can copy the pattern and then make the necessary modifications to the copy.

1. Select the pattern you want to copy.
2. Click the list next to the New Pattern button and then select Create Copy. A new operation with a similar name and a number appended to the end is created. For example: Pattern_2_2.
3. Modify the new pattern so that it is distinguishable from the pattern on which it is based.

Adding Attributes

An attribute is a selected area on an entity containing data that needs to be accessible via the model file.

After you've created an entity and added pattern to that entity, you're ready to add an attribute or attributes.

To add an attribute to an entity:

1. Use the cursor to select a text field on the host screen.

2. On the Attribute tab, click the New Attribute button. All of the other options on this tab will be unavailable.

3. By default, the attribute is named Attribute_1. To change the name, select it and type a new name in the Name box.

   The Design Tool records the position and other defining characteristics of the attribute.

   You can accept the Design Tool's default properties, or change them on the Attribute tab.

4. Click Apply to save your changes.

Some entities require that you add recordset information. After adding these elements to an entity, you can define operations to navigate between entities.

To copy an attribute:

After you create an attribute, you may need to create another that is similar. You can copy the attribute and then make the necessary modifications to the copy.

1. Select the attribute you want to copy.
2. Click the list next to the New Attribute button and select Create Copy. A new attribute with a similar name and a number appended to the end is created (for example, Password_2).
3. Modify the new attribute so that it is distinguishable from the attribute on which it is based.

To add colors to an attribute:

1. From the Settings menu, select Display... to open the Display Setup dialog box.

2. In the Item box, select a value.

   The Sample Text window shows the current colors for the selected item and whether any part of your current Terminal window actually has the same attribute.

3. In the Foreground (text) box, select a color.

   Any text matching the selected attribute immediately changes color as you move from color to color.

4. To set a color for a different attribute, return to the Item box.

5. Click OK to exit the Display Setup dialog box.

6. Click Defaults to reset all colors to their default values.

More information

• Customizing the Terminal

Adding Recordsets to an Entity

To add a recordset to an entity:

1. On the Recordset tab, select a scrollable area on the terminal screen and click the New Recordset button in the Name box.

2. By default, the recordset is named Recordset_1. To change the name, select it and type a new name in the Name box.

3. Configure your recordset using the Recordset Position, Layout, and Fields tabs.

4. Click Apply to save your changes.

To copy a recordset:

After you have created a recordset, you may need to create another that is similar. You can copy the recordset and then make the necessary modifications to the copy.

1. Select the recordset you want to copy.
2. Click the list next to the New Recordset button and select Create Copy. A new recordset with a similar name and a number appended to the end is created (for example, AcctTransData_2.
3. Modify the new recordset so that it is distinguishable from the recordset on which it is based.

Testing Recordsets

This is an example of testing a fetch record in the CICSAccts model.

1. On the File menu, choose Open and select CICSAccts.modelx.
2. Click Return to connect.
3. From the Entity list on the Entity window, select NameSearchResults.
4. Select the Recordset tab and click the Test button in the Name box.
5. In the Test Recordset dialog box, select Fetch Records from the Action box.
6. Click the Execute button.
7. View the results of the data fetch test in the Fetch returned box.

Fetch Records

To test a record fetch:

1. Open CCSDemo.modelx in the Design Tool.
2. On the Connection menu, choose Connect to localhost via Telnet.
3. From the Entity list on the Entity window, select NameSearchScreen.
4. Select the Recordset tab and click the Test button in the Name box.
5. In the Test Recordset dialog box, select Fetch Records from the Action box.
6. To filter out a record or records from within a recordset, click the Edit button to open the Filter String Edit dialog box.
7. Click the Execute button.
8. View the results of the data fetch test in the Fetch returned box.

Inserting a Record

To insert a specific record or multiple records into a recordset:

1. Confirm that SIDemo is running in the Host Emulator, then open SIDemo.modelx in the Design Tool.
2. On the Connection menu, click connect to localhost via Telnet.
3. From the Entity list on the Entity window, select CustomerPurchases.
4. Click the Recordset tab and select CustomerList from the Name box.
5. Click the Test button to open the Test Recordset dialog box.
6. Select Insert Record from the Action box.
7. In the Insert record box, notice that the Select and Customer fields have been created for this recordset and are listed in rows.
8. To insert a record, under the Value column, type B. JONES into the Customer text box.
9. Click Execute. If the insert is successful, the record contents should appear in the Terminal window.

Selecting a Record

There are two possible ways to select a record: by condition or by index. The following procedures use SIDemo.modelx as an example.

To select a specific record by condition in a recordset:

1. Confirm that SIDemo is running in the Host Emulator, then open SIDemo.modelx in the Design Tool.
2. On the Connection menu, click Connect to localhost via Telnet. Confirm that SIDemo is running in the Host Emulator, then open SIDemo.modelx in the Design Tool.
3. In the Entity box, select CustomerPurchases and click the Recordset tab.
4. Click the Test button to open the Test Recordset dialog box.
5. From the Action box, select Select Record.
6. Click the Edit button to open the Filter String Edit dialog box.
7. In the Filter String Edit dialog box, select Customer from the Recordset fields box, click the = button, and type the following in the Filter string box: Q. ARMSTRONG The filter string should appear as follows: CustomerList.Customer = "Q. ARMSTRONG"
8. Click OK.
9. In the Test Recordset dialog box, click Execute.

If the selection is successful, the record contents for Q. ARMSTRONG are displayed on the terminal screen along with the following message:

The selection operation reached an expected destination.

To select a specific record by index in a recordset:

This action is the analog of the SelectRecordByIndex method. If the record exists on an entity that does not contain any defined recordsets, the Test Recordset dialog box closeS.

1. Follow the procedures described in Step 1 through Step 4 above.
2. From the Action box, select Set Current Record Index.
3. In the Set the current record index to box, type 3, and click Execute. To check that your current record index is set to the line number you want, view the indicator (for example, Current record index: <line number> at the bottom of this dialog box.
4. Select Select Record from the Action box and click Execute.

If the select is successful, the record contents for Q. ARMSTRONG is displayed on the terminal screen along with the following message:

The selection operation reached an expected destination.

Update Current Record

To update the current record in a recordset:

1. Open Purchases.modelx in the Design Tool.
2. On the Connection menu, choose Connect to localhost via Telnet.
3. In the Entity box, select CustomerPurchases and click the Recordset tab.
4. Click the Test button to open the Test Recordset dialog box.
5. From the Action box, select Set Current Record Index.
6. In the Set the current record index to box, type 2.
7. Click Execute. To check that your current record index is set to the line number you want, view the indicator (for example, Current record index: <line number>) at the bottom of this dialog box.
8. From the Action box, select Update Current Record and click Execute. Look in the Update current record box and notice that Select appears in the Field column and the Value column is blank.

9. In the Value column, Type 1 and then click Execute.

   The value you entered (1), is displayed on line 3 of the Select column in the Terminal window.

Set Current Record Index

To set the current record index of a recordset:

1. Confirm that SIDemo is running in the Host Emulator.
2. In the Design Tool, open SIDemo.modelx.
3. On the Connection menu, click Connect to localhost via Telnet.
4. In the Entity box, select CustomerPurchases and click the Recordset tab.
5. Click the Test button to open the Test Recordset dialog box.
6. From the Action box, select Set Current Record Index.
7. In the Set the current record index to box, type 2.
8. Click Execute.
9. To check that your current record index is set to the line number you want, view the indicator (for example, Current record index: <line number>) at the bottom of this dialog box.
10. From the Action box, select Fetch Records and click Execute. Look in the Fetch returned box and notice that records were fetched beginning with line 3: Q. ARMSTRONG appears in the Customer column.

Defining Entities and Recordsets for Procedures

Host Integrator fulfills SQL queries from client applications by navigating to the pertinent entities in a host application that contain the table data and either reading, modifying, or deleting the data. A procedure's definition must specify all entities and recordsets that contain table data.

In addition to defining the entities and recordsets that contain table data, you can also define branching entities. These entities provide some flexibility for a procedure when it is traversing through a host application, as well as error entities that you can use to trap errors in a procedure.

• Adding Entities to a Procedure

  You must add every entity to a procedure that contains the attributes and/or recordset field that the procedure is able to query.

• Adding Recordsets to a Procedure

  Recordsets are areas on an entity that contain dynamically changing information, usually scrolling sets of data that are a result of a data fetch.

• Adding Branch Entities to a Procedure

  Use branch entities in procedures when an operation has alternate entity destinations. There are some cases where traversal is not deterministic, for example, when an operation has alternate destinations defined. These alternate destinations can be added as branch entities in a procedure. When the operation is executed at runtime, the path the procedure takes is determined by which branch entity is recognized after the operation completes. If none of the branch entities is recognized, the procedure fails.

• Adding Error Entities to a Procedure

  Error Entities are screens containing patterns that indicate an error has occurred in the procedure. You can define error entities by purposely entering bad data in a host application and capturing the resulting screen as an entity. Adding one or more error entities to a procedure is a good way to build error checking into your model.

More information

• Inserting a Recordset
• Inserting an Error Entity
• Inserting a Branch Entity

Creating Descriptions for Entity Definitions

The following options allow you to include descriptions in any exported documentation. This data is included in Web Builder projects or any documentation generated using Export options. This applies to Advanced Attribute Properties, Advanced Operation Properties, Advanced Recordset Properties, and Advanced Recordset Field Properties.

Click Advanced Properties next to the Name box on the corresponding Attribute, Operation, Recordset, and Recordset Field tabs to open these dialog boxes.