CREATE SESSION

Topic group Example

Creates a new session—now referred to as a workset—and immediately selects it.

Syntax

CREATE SESSION

Description

Use CREATE SESSION in an application that uses form-based data handling and the Xbase DML. Applications that only use the data objects generally do not need CREATE SESSION.

A workset is the more precise term for what was called a session in earlier versions of Visual dBASE and is used to encapsulate separate user tasks. It consists of the set of all 225 work areas and the current settings of most of the SET commands. There is always an active workset. When dBASE Plus starts, the settings are read from the PLUS.ini file and all work areas are empty. This is sometimes referred to as the startup workset.

Whenever you open or close a table or change a setting, that occurs in the current workset. Commands that affect all work areas, like CLOSE DATABASES, affect all work areas in the current workset only. Record locks are workset-based. If a record is locked in one workset, you cannot lock that same record from another workset; but you could lock that record if the same table is open in another work area in the same workset.

When you issue CREATE SESSION, a new workset is created and made active. A new unused set of work areas is created and all settings are reread from the .INI file. Any previously existing worksets are unaffected, except that they are no longer active. In fact, you cannot change anything about a dormant workset; you must make it active first.

Whenever a form is created, it is bound to the currently active workset. Any number of forms may be bound to a single workset. Each workset has a reference count that indicates the number of forms bound to it. The Command window and Navigator are both bound to the startup workset.

Whenever a form receives focus or any of its methods are called, its workset is activated. This means that all commands, functions, and methods take place in the context of a specific workset and have no effect on the tables or settings in other worksets.

Note

Worksets have no effect on variables.

When a form is released (either explicitly or when there are no more references to the form) its workset’s reference count is reduced by one. If that reduces the reference count to zero, the workset is also released.

Whenever a workset is released, any tables that are open in it are closed automatically.

The active workset’s reference count is also checked:

Just before another workset is activated (usually by giving focus to a form in another workset)

Whenever CREATE SESSION is executed (before the new workset is created)

When a form method has finished executing.

If the count is zero, the active workset is released. When a form method is finished, it also selects the workset that was active when the method started. So if you click a button button on a form that currently does not have focus, and that button’s onClick event handler (all event handlers are methods) has a CREATE SESSION command then the sequence of events is as follows:

1. Clicking the form causes a focus change. The active workset is checked; if its reference count is zero, it is released.

• The form’s workset is activated.

• The onClick executes, creating and activating a new workset.

• The onClick ends. If the reference count of the just-created workset is zero, which it would be if the method didn’t create any forms after the CREATE SESSION, it is released.

• The form’s workset, the one that was active when the method was executed, is reactivated. It is now the active workset.

Clicking the button again would only go through steps 3 through 5, because the form still has focus, so there is no focus change.

OODML

Use Session objects.