Using Data Sessions

Article
11/14/2006

To ensure that each user in a shared environment has a secure, exact duplicate of the working environment, and to ensure that multiple instances of a form can operate independently, Visual FoxPro provides data sessions.

A data session is a representation of the current dynamic work environment. You might think of a data session as a miniature data environment running inside one open Visual FoxPro session on one machine. Each data session contains:

A copy of the items in the form's data environment.
Cursors representing the open tables, their indexes, and relationships.

The concept of a data session is easily understood when you consider what happens when you open the same form simultaneously from separate workstations in a multiuser application. In this case, each workstation is running a separate Visual FoxPro session, and therefore has its own set of work areas: cursors representing open base tables, indexes, and relationships.

However, if you open multiple instances of the same form in a single project, on one machine, within the same Visual FoxPro session, the forms share the Default data session, representing a single dynamic work environment. Each instance of the open form open in the same Visual FoxPro session uses the same set of work areas, and actions in one instance of a form that move the record pointer in a work area automatically affect other instances of the same form.

Using Private Data Sessions

If you want to have more control over multiple instances of form, you can implement Private data sessions. When your form uses private data sessions, Visual FoxPro creates a new data session for each instance of the Form, FormSet, or Toolbar control your application creates. Each private data session contains:

A separate copy of each table, index, and relationship in the form's data environment.
An unlimited number of work areas.
Record pointers for each copy of each table that are independent from the base tables for the form.

The number of available data sessions is limited only by available system memory and disk space.

You implement private data sessions by setting the DataSession property for the form. The DataSession property has two settings:

1 – Default data session (the default setting).
2 – Private data session.

By default, the DataSession property of a form is set to 1.

To enable private data sessions

Choose one of the following options:

In the Form Designer, set the DataSession property of the form to 2 – Private data session.

-or-
In code, set the DataSession property to 2.

For example, type:
```
frmFormName.DataSession = 2
```
Note You can only set the DataSession property at design time. The DataSession property is read-only at run time.

When a form uses private data sessions, each instance of a form open on a single machine in a single Visual FoxPro session uses its own data environment. Using private data sessions is similar to running the same form simultaneously from separate workstations.

Equivalent multiple data sessions

Identifying Data Sessions

Each private data session is identified separately. You can see the contents of each data session in the Data Session window. You can also change the data session description through commands in the Load event code.

You can view the identification number for each data session by using the DataSessionID run-time property. The following example displays the DataSessionID property of a form named frmMyForm:

DO FORM frmMyForm
? frmMyForm.DataSessionID

If you activate the form using the NAME clause, you can use the form's name to access the DataSessionID property, as in the following code:

DO FORM MyForm NAME one
? one.DataSessionID

The DataSessionID property is designed only to identify a particular data session. Avoid changing the DataSessionID of a form instance because data-bound controls lose their data sources when you change the DataSessionID.

Updating Data Using Multiple Form Instances

While private data sessions generate separate work areas containing separate copies of a form's open tables, indexes, and relationships, every copy of the form references the same underlying base tables and base index files. When a user updates a record from one instance of a form, the base table referenced by the form is updated. You see the changes made from another instance of the form when you navigate to the changed record.

Locks taken on records or tables in one private data session are respected by other private data sessions. For example, if the user of data session 1 takes a lock on a record, the user in data session 2 cannot lock the record. If the user in session 1 opens a table exclusively, the user in data session 2 cannot open the table. By respecting locks taken by other data sessions, Visual FoxPro protects the integrity of updates to the underlying base tables.

Customizing the Environment of a Data Session

Because data sessions control the scope of certain SET commands, you can use private data sessions to establish custom SET command settings within a single session of Visual FoxPro.

For example, the SET EXACT command, which controls the rules used when comparing character strings of different lengths, is scoped to the current data session. The default setting for SET EXACT is off which specifies that, to be equivalent, expressions must match, character for character, until the end of the expressions on the right side is reached. You might want to enable "fuzzy" or equivalent searches by leaving SET EXACT set to OFF for the default data session; however, your application might contain a specific form that requires exact matches. You could set the DataSession property for the form requiring exact matches to 2, to enable private data sessions, and then SET EXACT to ON for that form. By issuing a SET command only for the form using private data sessions, you preserve the global Visual FoxPro session settings while enabling customized session settings for a specific form.

Overriding Automatic Private Data Session Assignment

When private data sessions for a form are in use, changes you make to data in one form are not automatically represented in other instances of the same form. If you want all instances of a form to access the same data and to immediately reflect changes to common data, you can override automatic data session assignment.

To override automatic data session assignment

Use one of these commands:

SET DATASESSION TO 1

-or-

SET DATASESSION TO

Both commands enable the default data session to be controlled by the Command window and the Project Manager.