Setting Up the Workgroup Engine
Understanding Workgroup Engine Configurations
The following topics discuss how to set up and use various configurations of the Workgroup engine, including use of the Gateway Locator Utility for a Gateway configuration:
Overview
This section explains the basic concepts and requirements of Workgroup engines. For in-depth information about the Workgroup engine, see Advanced Operations Guide. It contains technical details and instructions on setting up a Gateway configuration and redirecting locator files.
Installation Requirements
Every computer that may be used to access the same data at the same time must have a Workgroup engine installed on it.
Operating System Security
Only database server engines can enforce OS level file security based on the privileges assigned to the login user name. The Workgroup engine does not attempt to do this. In a small office, where Workgroup engines are most common, this can be considered a plus because they are usually short on networking experts, and the fewer barriers to successful data access the better.
When to Use Workgroup
There are three main configurations in which you would want to use the Workgroup engine.
Small Client-Server Configuration
The first configuration takes place when all the data is located on a single computer with a Workgroup engine installed, and there is limited sharing of data. This configuration is roughly equivalent to a small client-server configuration.
Peer-to-Peer Configuration
Another situation when you would want to use the Workgroup engine is when the data is distributed among the workstations. This is called a peer-to-peer topology. This configuration is used when each application typically stores much of its own data on the local hard drive, but periodically needs to access data from other workstations or share its own data with others.
In this configuration, each computer shares its data directory or directories. Any computer that needs access to that data maps one or more drives to the shared data directories. Then the Workgroup engine on each computer acts as a mini-server engine to read and write all changes to the data files on that machine.
Gateway Configuration
The third topology requiring the use of the Workgroup engine is when the data is stored on a file server where there is no MicroKernel engine. This can be a Unix server or other type of network file server that gets backed up regularly, but cannot support a MicroKernel engine. In this situation, the first Workgroup engine that opens files in a directory on the server becomes the Gateway to each file in that directory. The other workstations access the data in a client-server fashion through that Gateway engine.
The Gateway engine for a given directory identifies itself by creating a file named ~PVSW~.LOC in that directory. This file is called a Gateway locator file and contains the network name of the computer where the Gateway engine is located. Other Workgroup engines attempting to access this data read the locator file to find the name of the engine they must communicate with in order to access the data.
You can ensure that the same engine always services the files in a given directory by making the locator file read-only. This is called a
static gateway, also referred to as a
fixed gateway. See
To Set up a Fixed Gateway for more information.
The Gateway engine acts as a server engine as it reads and writes pages to the data files, allowing it to make the most use out of its cache. The Gateway feature is designed so that the ownership of any particular directory can change whenever the current gateway engine has no more client applications with any files open in that directory. When the last data file is closed in a directory by a given database engine, the engine releases and deletes the locator file. When the next engine opens a data file, that engine becomes the new gateway to the directory where the data file(s) resides.
What is a Gateway Engine?
A Gateway engine is a Workgroup engine that acts as the sole point of access to all data files in a particular directory on a remote file server. If several Workgroup engines are accessing the same database at the same time, they do not all open the files simultaneously, nor do they share the files. Rather, the first Workgroup engine to access that database becomes the temporary “owner” of those files, and all other Workgroup engines must access the data by contacting the Gateway engine. Only the Gateway engine has the files open and reads/writes the files. The other Workgroup engines act as clients, making requests to the Gateway engine acting as a mini-server engine.
Caution Make certain the Gateway computer is NOT shut down while users are still using it as a Gateway, or data loss can occur.
A Gateway engine only comes into play when no database engine is installed on the machine where the data files are, or when the database engine on that machine is not operating.
Setting Up a Small Client-Server Configuration
As explained in
Small Client-Server Configuration, you should use this set up when you have only a few workstations sharing data located on a central computer where you have a Workgroup engine installed.
If you have data located on many computers, or if you do not or cannot install a database engine on the computer where the data is located, you should use one of the other configurations.
►To Set Up a Small Client-Server Configuration
1 You must have the Workgroup Engine installed both on the central computer where the data is and on all computers expected to access the data.
Ensure that the Workgroup Engine on the central computer where the data is located is operational each time the computer is started, before any other database engines attempt to access the data. A Workgroup Engine starts by default if installed as a server. By default, Workgroup Engine is installed to run as a service for a fresh install. If the Workgroup Engine was installed as an application, ensure that the application starts if the computer is restarted. See
Running the Workgroup Engine as a Service.
Note You may inadvertently fall into a Gateway configuration if the database engine on the machine where the data is located is not started when the computer is started. If another Workgroup engine attempts to access the data and the local database engine is not running, the other database engine may establish itself as the Gateway for those data files.
You can resolve this situation by shutting down the computer where the data is located, and starting it again, while ensuring that no other computers request data before the local Workgroup engine is restarted. You may need to remove the file ~PVSW~.LOC from the data directory to ensure the Gateway is not reestablished.
The best way to ensure that only the Gateway services the file is to set a static gateway locator file using the Gateway Locator Utility.
2 Share the directory where the data is located so that other computers can map a drive to the data directory.
3 Ensure that each workstation expected to access the data can access the named database on the central computer. See
Named Database in
Advanced Operations Guide.
Setup is complete. The Workgroup engine on the machine where the data is located now acts as a mini-server, to fulfill all requests for data on that machine.
Setting Up a Peer-to-Peer Configuration
As explained in
Peer-to-Peer Configuration, you should use this set up when you have workstations sharing local data as well as data located on many different machines, and each machine has the Workgroup engine installed.
This configuration is similar to the small client-server configuration discussed above, except that now every Workgroup engine is sharing data as a server.
If you have data located on only one computers, or if you do not or cannot install a database engine on the computer where the data is located, you should use one of the other configurations.
►To Set Up a Peer-to-Peer Configuration
1 You must have the Workgroup engine installed on each computer where data is located, and installed on all computers expected to access the data.
Ensure that the Workgroup engine on each computer where the data is located is operational each time the computer is started, before any other database engines attempt to access the data. A Workgroup Engine starts by default if installed as a server. By default, Workgroup Engine is installed to run as a service for a fresh install. If the Workgroup Engine was installed as an application, ensure that the application starts if the computer is restarted. See
Running the Workgroup Engine as a Service.
Note You may inadvertently fall into a Gateway configuration if the database engine on a machine where data is located is not started when the computer is started. If another Workgroup engine attempts to access the data and the local database engine is not running, the other database engine may establish itself as the Gateway for those data files.
You can resolve this situation by shutting down the computer where the data is located, and starting it up again, while ensuring that no other computers request data before the local Workgroup engine is restarted. You may need to remove the file ~PVSW~.LOC from the data directory to ensure the Gateway is not reestablished.
The best way to ensure that only the Gateway services the file is to set a static gateway locator file using the Gateway Locator Utility.
2 On each computer where data is located, share the directory where the data is located so that other computers can map a drive to the data directory.
3 Ensure that each workstation expected to access the data can access the named database to which the data belongs. See
Named Database in
Advanced Operations Guide.
Also, ensure that each Workgroup engine can access any local data from its own physical drive.
4 Set up is complete. The Workgroup engine on each machine where data is located now acts as a mini-server, to fulfill all requests for data on that machine.
Each Workgroup engine also handles any local data access, that is, database requests from applications on that machine for data that resides on the same machine.
Setting Up a Gateway Configuration
As explained in
Gateway Configuration, you should use this set up only when you have data files on a computer where no database engine is installed.
If you have database engines installed on all machines, you should use one of the other configurations.
Note Your configuration may inadvertently function as a Gateway if the database engine on a machine where data is located is not started when the computer is started. If another Workgroup engine attempts to access the data while the local database engine is not running, the other database engine may automatically establish itself as the Gateway for those data files.
You can resolve this situation by specifying a permanent Gateway as described here or by restarting the computer where the data is located while ensuring that no other computers request data before the local Workgroup engine restarts. You may need to remove the file ~PVSW~.LOC from the data directory to prevent the Gateway from reestablishing itself.
The best way to ensure that only the Gateway services the file is to set a static gateway locator file using the Gateway Locator Utility.
Floating or Fixed Gateway
You can set up two different Gateway configurations. The default behavior is a floating Gateway configuration. In this configuration, the first engine to open the remote data files becomes the Gateway engine for that directory until all files in the directory are closed. Then the next engine to open the data files becomes the new Gateway. This configuration is the most flexible, but also can entail delays upon initial connection to the database, as the engine tries the different network protocols and checks for an existing Gateway engine.
Note Using a floating Gateway in a peer-to-peer configuration with multiple shared data sources is not recommended. This configuration is supported and it operates as designed, however, with multiple engines shuffling ownership among multiple data locations, connection delays may be significant. It is also possible to create a situation where a Workgroup engine on a remote machine serves as the Gateway for data located on your local hard drive. Obviously there is no reason to endure this delay when your local Workgroup engine can serve this data with higher performance.
You can avoid this situation by ensuring that the Workgroup engine on every computer is started when the computer is started. You must also ensure that someone logs on to each computer, because normally the Workgroup engine doesn’t start until a user logs on.
You can also avoid this situation by permanently assigning each machine as the Gateway for the data files located on it. See
To Set up a Fixed Gateway for information on how to perform this task.
The second configuration is called a fixed or permanent Gateway configuration. In this configuration, a specific engine is permanently assigned as the Gateway engine for a specific directory. If that engine is not running when another engine attempts to access the data, an error code results and the data is not available.
►To Set up a Floating Gateway
1 This is the default behavior. Ensure that each Workgroup computer can access the named database (and therefore its data). See
Named Database in
Advanced Operations Guide.
The Gateway assignment now floats dynamically as different Workgroup engines access the remote data.
►To Set up a Fixed Gateway
To specify a permanent Gateway engine for a given directory, you need only change the attributes of the ~PVSW~.LOC file to read-only, once it contains the name of the desired engine. There are several ways to perform this task.
Use the Gateway Locator Utility
1 Access Gateway Locator from the operating system Start menu or Apps screen.
2 In the Target Directory area, type in or browse for the directory containing the data files for which you wish to set up a permanent Gateway.
3 In the Directory Status area, click Change. In the dialog box that appears, click Assign a Gateway, then type in or browse for the network name of the computer that you want to be the Gateway. Click OK.
4 Back in the main Gateway Locator window, check Permanent assignment. Click Exit.
Use the DOS Command Line
1 Use the ATTRIB +R command at a DOS command prompt to change the attributes of the ~PVSW~.LOC file.
For example, if your current directory is the directory where the file is located, you can type the following command:
ATTRIB +R ~PVSW~.LOC
Use the Windows Explorer
1 Right-click the ~PVSW~.LOC file in the directory for which you want to make a permanent Gateway assignment. Choose Properties from the pop-up menu.
2 In the Properties window, on the General tab, click Read-only in the section labeled Attributes. Click OK.
Working with the Gateway Locator Utility
The Gateway Locator Utility provides control of and insight into any Gateway configuration you have on your network. This section explains how to use the utility for a variety of purposes.
This utility enables users to determine or change the Workgroup Engine which is being used as the gateway for the data files in a particular directory. The Gateway Locator utility is used only with PSQL Workgroup Engine.
The Gateway Locator operates by reading and manipulating the locator file, ~PVSW~.LOC, which resides in any directory which is assigned a Gateway engine. If this file is locked (in use), the Gateway Locator can only locate, not change, the Workgroup engine being used as a Gateway for that particular directory.
►To start the Gateway Locator Utility
1 Access Gateway Locator from the operating system Start menu or Apps screen.
Figure 1 Gateway Locator Main Dialog Box
Note The Gateway Locator can be used to set the gateway for any data directory. Data directory locations are not stored with the tool. Consequently, you must always set the directory path before you click Change.
2 In Target Directory, enter or browse for the directory path which contains the data files for which you wish to locate or change the Gateway engine.
3 The default target directory is the current working directory. Clicking the browse (...) button allows you to browse for the target directory, by bringing up the following dialog box:
Figure 2 Gateway Locator Browse Dialog Box
►Locating the Gateway Workgroup Engine
Once the target directory is selected, clicking the Refresh button causes the name of the Gateway engine for that directory (if such exists) to appear in the Gateway Assigned To box. If no Gateway exists for a particular directory, the box reads “unassigned.”
►Changing the Gateway Workgroup Engine
Once the target directory is selected, click Change to choose the Workgroup engine which you wish to serve as Gateway for a particular directory (this button is disabled if the locator file for that directory is locked.) The following dialog box appears:
Figure 3 Gateway Assignment Dialog Box
Enter or browse for the machine name you wish to serve as gateway.
Figure 4 Browse for Computer Dialog Box
Running the Workgroup Engine as a Service
By default, the Workgroup Engine is installed to run as a service for a fresh install. Running the Engine as a service allows the Engine to start automatically when the operating system starts. A user is not required to log in to start the engine. No tray icon appears when you run the Workgroup Engine as a service.
During installation, you can select to run the Workgroup Engine as a console application. Or, if you upgraded your Workgroup installation and you had the previous version installed to run as an application, the upgrade installation is also set to run as an application. In either case, if you decide that you would rather run the Workgroup Engine as a service, you change how it is run.
Configuration
To configure your Workgroup Engine to run as a Service as opposed to an application, you must reinstall Workgroup Engine. Choose
Run As Service on the Engine Settings dialog box during install. See
Installing PSQL Workgroup for Windows.
Note Running the engine as a service requires the Log On as Service privilege. If you select to run the engine as a service under a user account other than the default Local System account, you will need to modify the Log On Properties for the Service using the Windows Control Panel.
Note that on Windows platforms, a valid user name and password are required to access PSQL databases on another machine. "System Account" has no rights on other machines to PSQL databases.
If you want the PSQL Workgroup service to access databases on another machine, then you must specify a valid user name and password for the other machine, unless there is a running PSQL Workgroup available locally on the other machine that can be used to access the databases instead. Access the properties for the PSQL Workgroup service. (Double-click the service on the Services dialog.) In the Log On As section, check This Account and specify a valid user name and password.
Stopping the Service
If you want to stop and then restart the service (but do not permanently remove the service), then simply restart the machine.
You stop the service on Windows platforms just as you would any other service.
►Stopping the Engine as a Service on Windows
1 In the Windows Control Panel, click Administrative Tools, then double-click Services.
2 Right-click the service name assigned to the Workgroup engine and click Stop.
