Troubleshooting Tips and Techniques

Click these links to reference troubleshooting information for different aspects of your host application model.

Troubleshooting:

• Timeout Errors
• Error Patterns and Error Entities
• Tracing
• Recordsets
• Tables
• Host Connections

Timeout Errors

A timeout is the default length of time that a computer will wait for a task to be completed before the task is canceled. The cancellation of a task is usually indicated by an error message. Timeouts can almost always be adjusted by the user or system administrator.

Host Integrator uses multiple timeouts; client connection timeouts, connector method timeouts, host connection timeouts, and so forth. If you encounter a timeout error, it does not necessarily mean that you should increase the duration of the timeout. For example, if the host application is not arriving at an expected entity within 10 seconds, waiting longer is not going correct the situation. You should first investigate the error logs and make targeted model improvements.

Connector timeout

If a table procedure is returning a large amount of data (such as naavigating too many host screens or scrolling a large recordset), then the connector timeout may need to be increased so the client-side doesn't give up too early.

Client method timeout

A client method timeout may occur if you have a procedure returning a large number of records, or any operation or event handler that takes a long time to complete. For information on revising the method timeout to address client timeouts. See KnowledgeBase Article 10044.

Error Patterns and Error Entities

There are useful techniques associated with using error entities and error patterns when modeling a host application, specifically when dealing with character mode host applications. Using error conditions helps you to detect when an error has occurred while you're modeling and testing your host application model. Error patterns catch error messages displayed on the current entity, while error entities handle errors that result in a host error screen being displayed.

When creating both error patterns and error entities, it's possible to create a customized error message that enables you to detect what kind of error has occurred during an operation.

Error Patterns or Error Entities

When handling an error condition, you sometimes have the choice of setting up an error pattern or an error entity. When evaluating which to use, remember that error patterns require less processing overhead and are therefore recommended. If you're dealing with a problem associated with a starting screen, you will need to use an error entity.

Trapping error messages that result from writing attribute data to the terminal screen is often helpful in identifying errors. This is usually applicable to character mode host applications that produce error messages while you are writing data to the terminal screen.

To create an error pattern to trap a host application error message:

1. Encapsulate the error message in a pattern and add it to the entity.
2. On the Pattern tab, clear the Use in entity signature check box.
3. Click the Operation tab in the Entity window.
4. Click the Conditions button to open the Operation Conditions dialog box.
5. Under Error patterns, move the pattern from the Available list to the Error patterns list.
6. Under Error pattern, you can configure a text or an attribute value to be returned if an entity encounters an error pattern during an operation.
7. Click Close to close the Operation Conditions dialog box and save any changes.

Remember:

• Operation conditions can contain error patterns.
• No action can be associated with an error pattern.
• An error pattern can be a particular host message or a non-blank host message.
• Error patterns can be recognized any time during the operation processing.

Error Entities

A user-defined error entity enables you to handle a host error screen by defining a custom error message or returning attribute data as your error message when the error entity is encountered. Make sure to define an operation on this error entity that enables you to navigate back to your original entity. Do not define an error entity as your home entity; if error handling is required, use error patterns instead.

1. Select the entity from the Name box on the Entity window and click the Operation tab.
2. Click the Destinations button to open the Operation Destinations dialog box.
3. Select an entity from the Unassigned entities box and click the right arrow button to add it to the User-defined error entities box.
4. You can also select one of the following options from the Operation Destinations dialog box to customize an error message to appear when your error entity is reached:

Remember:

• Return text — Select this option to create any return text that will be displayed if the error entity is encountered during execution of this operation.

• Return attribute contents — Select one or more attributes to return as the contents of your user defined error message.

Tracing

The Design Tool provides the following types of tracing to aid you in the modeling process:

• Host Emulator recording
• Datastream tracing (for 3270 and 5250 block mode datastreams only)
• Debug tracing

Host Emulator recording

Host Emulator recordings capture negotiations between entities in your model and can capture the data sent to the host at the transport level. When you use the Host Emulator, these files can be played back to simulate the host environment without having a direct connection to the host. This feature is helpful if you plan to use the Host Emulator as a model testing tool during production and for offsite model development.

To create trace (.trc) files for the Host Emulator

1. On the Connection menu, point to Host Emulator Recording and choose Start. You must start the recording before you make the host connection.
2. Choose the file seed name and location for the recording. Recordings are saved, by default, in <My Documents>\RocketSoftware\Verastream\HostIntegrator\recordings. The file is saved with a .trc or .trc_GROOMED extension.
3. Click Trace. For every new session a new recording file is created.
4. Step through your model entities including any login and logout command lists. This records all the data traffic with the host.
5. Click Stop to terminate the recording. The trace file is groomed automatically, which makes it suitable to be played back immediately.

Recordings are played back using the options in the Administrative Console. You can disable automatic grooming using the View Settings option available from the Settings menu.

Datastream Tracing

Datastream tracing interprets 3270 and 5250 datastreams by capturing data transmissions to and from the host during a live connection. Tracing is intended primarily for diagnostic purposes. Use the model debug messages feature for more options on interpreting the datastream.

1. On the Connection menu, point Datastream Trace, and select Start Trace.
2. Type a name in the File name box and click Trace. By default, the .hst file is saved in the \<VHI install directory>\etc\tracing folder.
3. Navigate through the entities in question, and select Stop Trace.

To play back the datastream trace:

1. On the Connection menu, point to Datastream Trace, and select Play Back Trace.
2. Select the .hst file and click Play.

The trace navigation displays on the Terminal window, which enables you to see the sequencing of host writes to the terminal screen to track navigation in offline mode.

Playing back a trace does not redisplay the user's input and does not require a live host connection.

Debug Tracing

Debug tracing is a more intricate form of configuration tracing that is used to help debug the product. This form of tracing should only be used if the other forms of tracing have failed. Make sure to contact a technical support representative before proceeding with a debug trace. A trace configuration file (.cfgtrc file) and an actual trace file (.trace file) results from a debug trace.

Some reasons to create a debug trace:

• Possible transport difficulties.
• Session problems on the Host Integrator Server

To start and stop a debug trace:

1. Click the Debug menu, point to Debug Trace and select Start Debug Trace. The Start Debug Trace dialog box opens.
2. Enter a name for trace file in the File name box.
3. Click Start. From this point forward, all data transmissions to and from the host are recorded.
4. To stop the trace, click the Debug menu, point to Debug Trace and select Stop Debug Trace.

Recordsets

Modifying records in a recordset from the Design Tool can create synchronization problems between the Design Tool and the host. For example, if Host Integrator inserts the first record in a recordset and there are no indicators that it should wait for the host to commit to a modification and make a new blank record appear, Host Integrator reports this as an error. The issue is that the Design Tool refreshes the internal view of the screen in the Terminal window before the host has received the new data.

Use the Model Debug Messages utility to compare what the model expects the screen to be against the host data stream.

Inserting and Updating Records

To fix this modification issue, create an operation using one or more Host Events commands that makes Host Integrator wait until the host is done returning the new input record. Then, configure Host Integrator to execute this operation after a record insert or record update. This operation will finalize a recordset change and write the inserted or updated record to the host. This can be accomplished in the Design Tool by configuring the options in the Inserting records box or the Updating records box of the Recordset Operations dialog box or with a performOperation method using an AppConn data object.

Testing Recordset Fetching and Selecting

The following provide examples of recordset debugging that can be accomplished with the Test Recordset dialog box:

Fetch Records

• Only one screen of data is returned

  On the Recordset Tab, open the Recordset Operations dialog box. Check to see if you are missing a Page down operation.

• No data is returned

  Check the Current record index. If it is not zero, then set the current record index to zero and retry the fetch.

• Fetching records does not terminate. The Break button must be clicked.

  1. Check the termination condition of your recordset in the Recordset Termination dialog box.
  2. If the termination condition is correct, check the Page down operation to ensure that it is truly paging down on the host. A Page down operation that doesn’t actually page through the host data may cause the termination condition to fail.

• First screen is returned twice.

  The Page Down operation should not complete until the entire screen is displayed. The type of Wait operation for this situation varies by terminal type. - A number of blank records are returned along with the data.

  In the Recordset Options dialog box, select Skip blank records.

Any Action

• After executing an action, the Test Recordset dialog box just displays the message, "The current entity does not contain a recordset."

  The action that you performed navigated you to a different screen. For selection, this is generally the expected result. If this happens as the result of a fetch or an insert, there may be a problem with a scrolling operation or an insertion operation resulting in unexpected navigation.

Select Record

• A selection operation did not reach the expected destination.AND It did navigate to a different screen.

  There is probably something wrong with the selection operation itself. Check to make sure that the expected destination and alternate/intermediate destinations for the selection operation are correct.
  - A selection operation reached the expected destination, but the wrong record was selected.

  1. Open SIDemo.modelx in the Design Tool.
  2. Select CustomerPurchases from the Entity box.
  3. Select the Recordset tab, and click the Operations button.
  4. In the Scrolling box, notice that LineDown is selected from the Line down box.
  5. To view details about the LineDown operation configured here, open the Operation tab and select LineDown from the Name box.

Tables

• Executing an SQL query results in no records found

  If you execute an SQL query against a table and do not find any records even though they exist, the Design Tool is unable to resolve your query into a valid procedure: You need to create one or more procedures that can access the table data.

• A valid procedure returns no data

  It's possible that a post-fetch filtering operation removed the data you were trying to retrieve. Table data is case sensitive: Be sure you are using the correct case when trying to retrieve data

Host Connections

You may not be able to connect to the host for the following reasons:

• The host and transport settings you specified in the Session Setup dialog box are not being recognized by the Design Tool. Verify your settings are correct and try connecting again.

• If you see a blank screen after establishing a host connection, the problem may be that the host has sent a disconnect to the Design Tool. Some hosts do this if they don't recognize the terminal type you have selected. When the host sends a disconnect, the Design Tool displays the following message in red on the bottom of the terminal screen:

  Your connection to <host name> has been terminated

• To solve this, select a different model ID in the Session Setup dialog box and try connecting again.

• The host may be unavailable temporarily or the network hardware may be malfunctioning. Check with your system administrator or try connecting again later.

• The network hardware may be malfunctioning. Check with your system administrator or try connecting again later.

If you suspect a host problem could be associated with running the model itself, try deleting a login command list if present. This will allow you to see the individual steps involved in the sequence and may resolve any issues in timing associated with the command list.