Choose a Database Cursor

When HotDocs connects to the database and identifies the information it needs to retrieve, it uses what is called a cursor. Just as a cursor in a word processor document allows you to move around and select text in a document, a database cursor allows HotDocs to scroll through and select records from a database table.

A database component can use one of two types of cursors when retrieving data from a database table: client cursors and server cursors. By default, HotDocs uses a client cursor; however, you can choose to have it use a server cursor. The following is a discussion about the advantages of each.

Client Cursors

A client cursor retrieves all the data in the result set (possibly across the network) to the user's machine, and manipulates the data there. The advantages of this are:

• End users will have fast scrolling and full ability to change sort order.
• The data is only pulled across the network one time.
• Server resources (connections) are freed as soon as the data is retrieved. No server connection is maintained while the user is interacting with the database component, selecting records. This has minimal impact on server resources.

The primary disadvantage of client cursors is that for very large result sets, the initial loading of the data across a network consumes bandwidth and can be time consuming. That is why, in HotDocs, it is recommended that you always use filters to minimize the size of the result sets from which users will choose. (See Limit the Number of Database Records from Which a User Chooses.)

Server Cursors

Unlike a client cursor, a server cursor opens the connection to the database and leaves it open until the user leaves the database selection dialog. This may be desirable in a few circumstances, such as when a large result set is required and the initial performance of a client cursor is prohibitive. However, the disadvantages of a server cursor are:

• User scrolling can be slower, as only the displayed data is retrieved from the database at one time.
• A connection to the database server must be maintained the whole time the user is selecting records from the database. Also, network traffic may be impacted if the user scrolls through the data repetitively.
• The user cannot change the sort order of the displayed results.
• If the user applies filters to very large result sets, performance and network bandwidth usage can be negatively impacted.

If you're accessing a database that is located on your local machine, there may not be a huge performance difference between client and server cursors. The biggest difference in this case is that server cursors will not allow you to change the sort order of the data you are viewing during the interview.

Because of these limitations, it is recommended you use client cursors—unless you have a specific reason to choose otherwise.

Once you decide which type of cursor best fits your needs, you can specify this option at the Options tab of the Database Editor.

To specify which type of cursor you will use

1. Open the existing database component for editing. (See Edit a Database Component.) The Database Editor appears.
2. Click the Options tab. The window changes to show several options for the component.
3. Choose one of the following options:
   • Select Use disconnected (client) record set to use a client cursor.
   • Clear Use disconnected (client) record set to use a server cursor.