Recordset Tab

The Recordset tab contains all of the settings used to define recordsets on a selected entity. If you've just added a new recordset to your model, the following options will be available:

The Name box contains the name or names of the currently defined recordsets. When you add a new recordset to an entity, a default name, such as Recordset_1, is generated. Use the buttons next to the Name box to add and delete recordsets. To further configure your new recordset, click the Advanced Properties or the Test button.

Position tab

This tab contains options used to determine the position of a recordset on the terminal screen.

• Top - Choose either Fixed Position, Relative to Cursor, or Relative to Pattern to describe the top position fo the recordset on the host screen. Fixed Position is selected by default and the Row and Col coordinates are calculated for you.
• Bottom - Choose either Fixed Row, Relative to Top, or Relative to Pattern to determine the bottom position of the recordset on the entity. Fixed Row is the default selection and the row coordinate is calculated for you.
• Width - The width of the recordset in terminal screen columns. By default, the Design Tool provides this information automatically when a new recordset is added.

To configure advanced recordset features, click:

• Operations
• Termination
• Options

Advanced Recordset Properties

The Advanced Recordset Properties dialog box provides the following options:

Event Handler

Use the options below to create, edit, attach, and view properties of an event handler for the recordset.

- Click this button to create a new event handler for the attribute. Use the list to select an existing attribute event handler. The selected event handler is attached to the attribute 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.

Recordset description

Type a description of the selected recordset. This data is included in Web Builder projects or in any exported XML- or HTML-based documentation documentation.

Recordset Operations

Operations can be defined for recordsets on the Operation tab and then configured in this dialog.

• Scrolling- Configure how to scroll through recordsets on the terminal screen by matching already defined operations with the following options:
• Selection - Certain recordsets allow you to select a record and then move to another entity for more information about that record. To encapsulate this required action, create a selection operation.

To view an example of a selection operation:

1. Open the SIDemo example and navigate to the CustomerPurchases entity.
2. Open the Recordset Operations dialog box.
3. Under Selection, view the choices in the Selection operation list.
4. To view the commands in these operations, click the Operation tab and select an operation from the Name box.
5. View the commands in the Command list box.

From a data object or tables, the API developer can choose to getCurrentRecord (scroll to a specific record in a recordset and return its contents) or fetchRecords (fetch up to the maximum rows of data from the Host Integrator Server for the current recordset of the current entity). The expected result of selection is to navigate to the entity that contains the additional information. For more information, search for getCurrentRecord or fetchRecords in the Host Integrator API Reference.

If the host supports this navigation by selection, select the Host allows navigation by record selection check box and select a defined operation from the Selection operation list. To test this operation, click the Test button from the Recordset tab.

• Inserting records - Some hosts allow you to directly insert records as part of a recordset on an entity. Use the options in this dialog box to configure your model to execute an operation before and after a single record insertion. If your host supports multiple record inserts, select the Host supports multiple record inserts check box described below and configure the model to instantiate the insertion using a combination of an operation stored in the model file and the new InsertRecords method available in your preferred Host Integrator connector.

Select the Host supports direct insertion check box and choose from the options described below.

If you attach an event handler to the recordset that has an Insert Record event implemented, a lightning bolt displays to the left of this option. This is a reminder that the event handler may include logic that overrides or extends any of the settings you configure.

• Updating records - Some hosts allow you to directly update a new record as part of a recordset on the terminal screen. To deal with this scenario, select the Host supports direct record update check box and choose from one or both of options below.

If you have configured an operation that executes prior to or after a group of records is to be inserted, invoke the operation using the new PerformEntityOperation method available with your preferred Host Integrator connector instead of the using the options in this dialog box. Use the Recordset Test dialog box to make sure your records are being properly added to the recordset.

Recordset Termination Options

Set the options needed to recognize when the end of a recordset has been reached. On the Scroll Up tab configure the information needed to define how to recognize when the first page of the recordset is reached. Once the first page is reached, it no longer makes sense to continue scrolling up. Choose Scroll Down to configure how to determine when the end of a recordset has been reached and what to return from the data in the last page of the recordset.

Scrolling operations must be configured on the Operation tab before you can configure items on the following tabs. To view an example of a PageDown and a PageUp operation, open the Pine model and select the AddressBook entity.

If you attach an event handler to the recordset that has an Is Terminated event implemented, a lightning bolt is displayed to the left of this option. This is a reminder that the event handler may include logic that overrides or extends any of the settings you configure below.

Scroll Up

Use this tab to define how Host Integrator is to recognize that it has reached the first page of a recordset (at which point it no longer makes any sense to continue scrolling up).

**Scroll termination criteria (Scroll Up)** -  The options in this group define a set of behaviors that a host application might use to indicate the first page of a recordset. The options you select from this set are defined as "termination criteria," which let Host Integrator know that it has reached the beginning (first page) of a recordset. If you select multiple termination criteria, Host Integrator assumes the beginning of the recordset is reached as soon as any one of the selected criteria is satisfied.

• Scroll operation results in same recordset data — The records displayed after the Scroll Up operation are the same as before the operation.
• Screen contains __ blank record(s) — The screen after the Scroll Up operation contains the specified number of blank records.
• Screen contains __ repeated record(s) — The screen after the Scroll Up operation contains the specified number of identical records.
• Screen contains pattern — The specified pattern is present in on the screen after the Scroll Up operation.
• Screen has condition — Select this check box and click the Edit button to open the Condition Edit dialog box. Use this dialog box to construct a logical statement that defines the beginning of a recordset.

Scroll Down

Scroll termination criteria (Scroll Down) - The termination criteria define a set of behaviors that you set to determine how the Host Integrator knows that it has reached the end (last page) of a recordset. If you select multiple termination criteria, Host Integrator assumes the end of the recordset is reached as soon as any one of the selected criteria is satisfied. The criteria are tested in the order they are listed in this dialog box, for example Scroll operation results in same recordset data is first,and so forth.

• Scroll operation results in same recordset data — The records displayed after the Scroll Down operation are the same as before the operation.
• Scroll operation results in entity change — The Scroll Down operation triggers the recognition of a new entity.
• Screen contains __ blank record(s) — The screen after the Scroll Down operation contains the specified number of blank records.
• Screen contains __ repeated record(s) — The screen after the Scroll Down operation contains the specified number of identical records.
• Screen contains pattern — The specified pattern is present in on the screen after the Scroll Down operation. The Learning to Use Host Integrator tutorial employs this strategy to recognize the end of the AccountList recordset (in the Terminating the page-down operation section).
• Screen has condition — Select this check box and click the Edit button to open the Condition Edit dialog box. Use this dialog to construct a logical statement that defines the end of a recordset.
• Max number of Page Down operations — This value sets the maximum number of Page Down operations that are executed before an error message is sent. The default number of operations is 1000, which in normal usage should never be reached, but setting a maximum value ensures that if a termination option on the same page is in error, an endless loop cannot occur.

Exclude records on last screen

Use these options to determine how Host Integrator will handle recordset data when it recognizes that it has reached the last page in a recordset.

Select Exclude records repeated from previous screen to stop Host Integrator from returning records from the last page, if they are identical to those records on the previous page.

The following options specify where you want Host Integrator to stop returning data from the last page in a recordset. If you select more than one of these options, Host Integrator stops returning data after one of the options is satisfied.

• Read until __ blank record(s) are found — No records are returned after the specified number of blank records is found.
• Read until pattern — No records are returned after the specified pattern is found.
• Read until record with condition — Select this option and click Edit to open the Condition Edit dialog box. Using this dialog box, construct a logical statement describing a condition to indicate where to stop returning records.

Recordset Options

Click the Options button on the Recordset tab to open the Recordset Options dialog box. Configuring filters and host scrolling behavior gives you more flexibility in sorting through recordsets when developing a host application model.

Current record preferences

Configure the options below to describe the properties of the current record in a recordset. The process of finding the current record is also referred to as recordset synchronization. When Host Integrator arrives at an entity with a recordset, it will always indicate the current record is at a record index of 0, which means before the first record. Any subsequent fetch of data will then start with the first record and proceed normally.

In some cases, you may not be primarily interested in fetching data. For example, you may instead want to select a record and navigate to another entity to view or edit details about it. In these cases, the record that the host claims is current may be important information for Host Integrator since the host's current record may not always be the first record.

If the host's current record is not always the first record, the model needs to provide the ability for Host Integrator to discover which record is current, so Host Integrator can calculate the number of LineDown or LineUp operations to execute.

This is most applicable to character-mode hosts; in block mode, the host does not typically designate a current record and Host Integrator can freely choose the record its client desires. Note: The current record definition defined here can also be used for recordset synchronization in procedures.

• Use first record on the current screen — Default. Select this option to assume the first viewable record on the terminal screen as the host's current record.
• Use current cursor position — Select this option to designate the record that contains the cursor as the host's current record.

• Record contains pattern — Select a pattern to use as the indicator of the host's current record location. See the AddressBook entity of the Pine model for an example.

  Tip

  On a character mode host, define a pattern with reverse video in the recordset region, then select that pattern from this list to define it as a way to discover the current record.

  If you want Host Integrator to make its current record match that of the host, use the SetCurrentIndex method and pass the SyncToHost parameter in your client application. Search for SetCurrentIndex in the Host Integrator API Reference for more information.

Excluding records

Configure the following options to create recordset filters that remove unneeded data sent by the host:

• Exclude consecutive repeated records — Select this check box to filter out records that appear at the bottom of one terminal screen and then repeat at the top of the next screen. Note: If the host you are creating your model for never repeats records, clear this check box.
• Exclude blank records — Select this check box to filter out blank records that appear on a terminal screen. It is possible that some field delimiters will not be seen as blank and will therefore prevent the record from being excluded. Use Exclude records matching condition instead and test if each individual field is blank.
• Exclude records matching condition — Select this option to specify an exclusion condition for the recordset using the condition editor. You can specify a regular expression as part of the condition.

Scrolling behavior

Configure the following options to indicate in the model file how the host handles recordsets that overlap between two screens:

• Host starts each screen with new record — Select this option if the host begins each new screen with a new record after scrolling down to the next screen. This indicates that the result of a PageDown operation will be a new set of records without any repeated records from the previous screen.

• Host repeats records on new screen — Select this option if the host repeats records as a way of having continuity between screens when scrolling is executed. For example, the last record on one screen may appear as the first record on the next screen after a PageDown operation has been executed. If the host uses this pattern consistently, select this option and configure one of the following options in the Repeated record preferences box:

• Assume __ repeated records — Select this option and enter the number of expected repeated records.

• Dynamically determine repeated records — Select this option to instruct the Host Integrator to recognize repeating records.

• Host overlaps records across screens — Select this option if the host begins a record on one screen and ends that same record on the next screen after a PageDown operation has been executed. If the host uses this pattern consistently, select this option and configure one of the following options in the Overlapping record preferences box:

• Assume no repeated data — Select this option if the host application does not repeat data when a record overlaps from one screen to the next.

• Dynamically determine repeated data — Select this option to instruct the Host Integrator to recognize if there are any repeating records when records overlap from one screen to the next.
• Skip records not contained on a single screen — Select this option to instruct the Host Integrator to ignore records that are not visible on a single screen.

Layout tab

This tab contains options used to define the layout of a recordset. Click one of the following for more information:

• Column location
• Record size

Column Location

Use the following options to define a recordset that displays more than one entry per line:

• Single Default. One entry per line.

• Multiple Select this to enable the up and down arrows and three-column grid (Column, Start, and End) controls. As you change the total number of columns in a selected recordset, the grid control will list the changed entries under Column.

  The Start and End controls represent the start and end terminal screen columns for each recordset column. As you increase or decrease the total columns with the up and down arrows, the grid will be updated to divide the width of the recordset evenly among all columns. The terminal screen will also be adjusted as the number of columns changes.

Record size

Allows you to define the size of the each recordset with the following options:

• Fixed - Default. Select this if your recordset takes up a set number of rows. The default is one row.
• Variable - Select this option to specify where the beginning and end of a recordset are on an entity. When selected, other delimiter options are available.
• Delimit by - Select an option to specify delimiters with text and the horizontal placement of the text within a recordset. The following options are provided: <Blank line> (default), <Any text>, <Any number>, or <User specified text>.

If you select an option other than <Blank line>, click the Advanced Delimiter Properties button to open the Advanced Recordset Delimiter Properties dialog.

Select the Delimiting text is also data check box to treat the delimiting text as data. By default, the Host Integrator assumes the delimiter is a visual separator between records rather than data. If the delimiting text is data, select one of the following options:

• Last field in current record
• First field in next record

Advanced Delimiter Properties dialog

Under Record size in the Recordset Layout tab, click the Advanced Delimiter Properties button to open the Advanced Recordset Delimiter Properties dialog box. Select the Delimiting text is also data check box to treat the delimiting text as data. By default, the Host Integrator assumes the delimiter is a visual separator between records rather than data. If the delimiting text is data, select one of the following options:

• Start col - If you select <Any text> or <Any number> in the Delimit by box, select an option from this list to specify how the delimiter should be handled by the Design Tool. The following options are provided: Any Column or First Column (default). You can also numerically select your start column by using the up and down arrows.
• End col - Specify the end column of your recordset to match the End specified in the Column location box.
• Text (type or select it from the terminal screen) - If you selected <User specified text> above, use this text box to type the text you want to use for your delimiter. If you select a portion of the terminal screen that falls within the recordset and click the ! button, the Design Tool will update and transfer the written contents to the text control and the horizontal location to the column control.

For VT sessions and some character mode HP sessions, the Field type and Text color check boxes are replaced with these options:

• Brightness - Specifies the brightness level of a static area added as a pattern on the terminal screen. Brightness can be normal (most screens and text) or half (which makes the characters appear dimmer). The default is No.
• Blink - Specifies that the text added as a pattern blinks on the terminal screen. The default is No. To change the color of a display attribute in the Design Tool, use the Display Setup dialog box on the Settings menu.
• Video - Specifies the video type of a pattern on the terminal screen. There are two types of video: Normal (often white characters on a black background) and Reverse (black characters on a white background). The default is No.

• Underscore - Specifies whether or not characters in a pattern appear to be underlined. The default is No. To change the color of a display attribute in the Design Tool, click Display on the Settings menu to open the Display Setup dialog box.

• Case sensitive - Specifies whether or not text, either typed or selected from the terminal screen, will be stored as case sensitive text in your model.

• End of screen is always a delimiter - Select this check box if you want the Host Integrator to always start a new record after iteration.

Recordset — Fields tab

This tab contains options used to define fields within recordsets. Click one of the following for more information:

• Cache all field writes
• Name, Start, End, and Key
• Type
• Read
• Write

Cache All Field Writes

Creates a temporary storage area for data assigned to recordset fields. To globally configure all recordset field data to be cached on new entities, select the Cache all field writes box on the Recordset Preferences dialog box. To cache recordset field data on a selected entity, select the entity in the Entity window and select the Cache all field writes box on the Recordset Fields tab.

When data is assigned to a field from within the Design Tool or from a Host Integrator API, it will be stored in this area rather than the default behavior of being written directly to the terminal. In an operation, field data can be assigned using write commands like DefaultValue and TransmitToField.

When using a Host Integrator connector, field data is assigned with methods like UpdateRecords or UpdateRecordByFilter.

When Cache all field writes is selected, the field data assigned by the Design Tool or the Host Integrator connector is temporarily stored until an operation issues an UpdateAttribute or UpdateAttributes command to write the stored data to the terminal screen.

Alternatively, an operation can call UpdateAttribute for each field in the desired order, inserting other commands in between as needed to modify cursor positioning, synchronize with the host state, or meet any other requirements to be executed by the operation.

Name Start End and Key

Before you can define a field on a recordset, you need to add fields to your recordset.

To add a field to a recordset:

1. Select an area within the recordset on the terminal screen that contains specific data and click the New Field button. By default, a name and the start and end offsets of the field are provided by the Design Tool. To change the name of the field, place your cursor in the Name text field and type a new name.
2. To delete the field, place your cursor within the field definition in the Entity window and click the Delete button.

Use the following options to further define the field you just created:

• Name - The name of the field.
• Start - The start offset within a field. By default, the Design Tool provides the start coordinate of the field you have selected.

• End - The end offset within a field. By default, the Design Tool provides the end coordinate of the field.
• Key - Select this check box if the name of this field returns one unique record. If you mark multiple fields as a key, the combination forms a key that appears in the exported documentation to aid the API developer in fetching specific pieces of data.

To create variable records in a recordset:

1. Add a recordset to your model.
2. On the Recordset Layout tab, select Variable under Record size.
3. Select an option from the Delimit by box. For example, select <Any text> and then specify the start and end column of the text that appears in the first row of a recordset.
4. Open the Advanced Delimiter Properties dialog box. If you selected a delimiting property that is also data in the recordset, like the <Any text>* option described above, configure the options in this dialog.
5. Click the Recordset Fields tab, and add fields to your recordset.
6. On the last field of the recordset, delete the column number in the End box and type the letters eor, which notifies the Host Integrator that this is the end of the variable record that you've created.

Type

Since configuring type options is possible for both attributes and recordset fields, select either the Attribute Properties tab or the Recordset Fields tab to view the Type box. These options allow you to specify whether or not data can be accessed by one of the Host Integrator connectors. If both Read and Write are cleared, the Host Integrator will reject any attempt to save the entity.

The choices include the following:

• Read - Select this check box to allow Host Integrator to read the host data contained in this attribute or recordset field at runtime. By default, this option is selected if protected fields exist on the entity. Note: The Read check box should not be selected if the attribute or recordset field contains or is to contain secure information such as a password.

• Write - Select this check box to allow Host Integrator to write host data to this attribute or recordset field at runtime. This check box is available even when an attribute or field is not writable to cover cases the protected state can change dynamically based on the data sent from the host. Note: When configuring a Write attribute, do not use the Any Row or Any Column to specify start position or end position.

• Hidden - Select this check box to hide the existence of the attribute or recordset field from one of the Host Integrator connectors.

• Enable terminal attributes - Select this check box to make terminal attributes accessible from a Host Integrator connector. Note: You must select this check box to enable and read terminal attributes using one of the Host Integrator APIs, specifically when using the EnableTerminalAttributes method. Search for "EnableTerminalAttributes" in the Host Integrator API Reference for more information.

Read

Configuring read options is possible for both attributes and recordset fields. Select either the Attribute Properties tab or the Recordset Fields tab to view the Read box. These options give you the ability to configure how Host Integrator processes terminal data that is read by allowing you to remove any set of spaces or symbols from the retrieved data.

Use the following options to configure how data is read:

• If empty, fill from last record with valid data. Select this check box to add a value from the last record to an empty field in the retrieved data. Note: This option appears on the Recordset Fields tab only.

  Example: An empty retrieval might be a field, such as "Mr.," that is programmed to be saved in one record in order to save space when consecutive records are encountered. This field is copied by the host application until an instance of "Mrs." appears. When this data is fetched by an API developer using one of the Host Integrator connectors, an empty field is returned because the host application has only saved "Mr." for one record—all of the other records return an empty field.

• Remove trailing blanks. Select this check box to remove trailing blanks from data read by Host Integrator.

• Remove leading blanks. Select this check box to removing leading blanks from date read by Host Integrator.

• Advanced. For more extensive substitution options, click Advanced.

Write

Since configuring write options is possible for both attributes and recordset fields, select either the Attribute Properties tab or the Recordset Fields tab to view the Write box. These options allow you to erase to the end of an attribute or or configure support for scrollable text.

• Erase to end of attribute. Select this check box to concatenate as many spaces as necessary to make the length of the input match the length of the attribute. For IBM terminal models, an Erase to end of field operation is performed if the attribute's location coincides with a terminal field. If the location does not coincide with a terminal field, Host Integrator uses spaces. This option appears on the Attribute tab only.

• Erase to end of field. Select this check box to concatenate as many spaces as necessary to make the length of the input match the length of the recordset field. This option appears on the Recordset Fields tab only.

• Scrollable text. Select this check box to add support for writing more characters to an attribute than the host would normally allow. This means that the length validation of the attribute or recordset field is bypassed by Host Integrator.

• Advanced. For more extensive substitution options, click Advanced. For example, you can prepend or append a constant string to a data input. The resulting string will be checked for length and type restrictions.

Advanced Recordset Fields: General Properties

• Event Handler. Use the options below to create, edit, attach, and view properties of a recordset field event handler(/event-handler-reference/#recordset-field-events).

  Click this button to create a new event handler for the recordset field. Use the list to select an existing recordset field event handler. The selected event handler is attached to the recordset field 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.

• Field description. Type a description of the selected recordset field. This data is included in Web Builder projects or any documentation generated using Export options.

Advanced Recordset Fields: Character Mode Properties

The Character Mode tab of the Advanced Recordset Field Properties dialog box provides the options below. The settings on this tab are unavailable if your model is for a 3270 or 5250 terminal type.

Character mode data entry.

If you are working on a character mode host, such as HP or VT, direct the Host Integrator to treat this field in any one of the following ways:

• Don't wait for echo (Default) — Select this option to transmit the string to the host and immediately move to the next action. Always use this option for block mode applications. For character mode applications, use this option only when you know that data will not be echoed back to the terminal screen. For example, many times alphanumeric keys are used to move between screens and are not echoed.

• Wait for same number of characters to echo — Select this option to wait for the same number of characters to be sent back to the terminal screen after data has been transmitted to the host. To detect the number of echoed characters, Host Integrator transmits the data and waits for the cursor position to move the same number of columns as the length of the data transmitted.

  For example, if you transmit the name George as your password, a host will often echo six spaces instead of the original text. With this option selected, Host Integrator waits for the cursor to move six columns from the cursor position when the name George was transmitted to the host before moving on to the next command.

• Wait for string to echo at cursor — Select this option to wait for the exact data string to be written back to the terminal screen after data has been sent to the host. This is the most robust option to select when working with character mode hosts. With character mode applications, the cursor must be wherever characters are being written to the screen. For this reason, use this option to synchronize with the host application.

• Wait for next tabstop — Select this option to wait for the cursor to appear at the next tabstop after transmitting data. If tabstops have been defined on the Cursor tab, then the Host Integrator waits for the cursor to appear at one of the defined locations. If no tabstop definitions are applicable, then the Host Integrator waits for the cursor to be anywhere on the screen that is outside the attribute or recordset field to which the data is being written.

• Wait for next tabstop or string to echo at cursor — Select this option to wait for the exact data string to be written back to the terminal screen or to wait for it to appear at the next appropriate tabstop. This option is not recommended.

Advanced Recordset Fields: Operations Properties

The Operations tab for the Advanced Recordset Field Properties dialog box provides the following options for configuring operations to be executed before or after writing to a recordset field:

• Execute operation before writing to field — Select a configured operation to be executed before data is written to the selected field.

• Execute operation to autotab on underfill — Select a configured operation to be executed when recordset field data does not completely fill in the length of the field.

  Tip

  Create an operation that automatically tabs to the next input field or an operation that traps an error. For example, if the data input is always a set length, like a social security number, create an operation that includes an error pattern as an operation condition.

  The option is typically used with character mode hosts. When data doesn't fill the recordset field, the behavior of a character mode host application can often be less predictable than a block mode host application.

• Execute operation after writing to field — Select a configured operation to be executed after data is written to the selected field.