General Reference > Getting Started Guide > Setting Up a Workgroup Engine
Setting Up a Workgroup Engine
The following topics discuss how to set up and use various configurations of Workgroup Engine, including use of the Gateway Locator utility for a gateway configuration:
Overview
This topic explains the basic concepts and requirements of Workgroup engines. For in-depth information about Workgroup Engine, see Advanced Operations Guide. It includes 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 file security at the operating system level 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 the fewer barriers to successful data access, the better.
When to Use Workgroup
Typically, Workgroup engines use one of three configurations: small client-server, peer-to-peer, and gateway.
Small Client-Server Configuration
This configuration is useful when all data is located on the single computer where the Workgroup engine is installed, and data sharing is limited.
Peer-to-Peer Configuration
A peer-to-peer topology may be called for when the Workgroup engine must access data distributed across more than one workstation. This configuration is used when applications store much of their own data on their local hard drive, but periodically they need to access data on other workstations or share their local data with them.
In this configuration, each computer shares its data directories. Any remote computer that needs access to the data then maps one or more drives to the shared 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 Workgroup topology is for data stored on a file server where there is no MicroKernel engine. This system can be a Unix 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 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. For other Workgroup engines to communicate with the gateway engine to access its data, they must read the locator file to find it.
You can ensure that the same engine always services the files in a given directory by making the locator file read-only. This gateway is permanent and is called 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 files reside.
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 or 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. Workgroup Engine starts by default if installed as a server. By default, Workgroup Engine is installed to run as a service for a fresh installation. If 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 fixed 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. Workgroup Engine starts by default if installed as a server. By default, Workgroup Engine is installed to run as a service for a fresh installation. If 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 fixed 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 setup 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 Worksgroup engine configuration may inadvertently function as a gateway if the database engine on a system where data is located is not started when the computer is started. If another Workgroup engine tries 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 fixed 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 does not 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 permanent and is called a fixed 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. Be sure that each Workgroup installation can access the named database and its data. See Named Database in Advanced Operations Guide.
The gateway assignment now floats dynamically as different remote Workgroup engines access data from their respective locations.
To set up a fixed gateway
To specify a permanent gateway engine for a given directory, you need to 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 or in ZenCC from the Tools menu.
2. In the Target Directory area, enter 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 a Command Prompt
Use the attrib +r command at a command prompt to change the attributes of the ~PVSW~.LOC file.
Use Windows Explorer
1. In the directory where you want to make a permanent gateway assignment, right-click the ~PVSW~.LOC file and select Properties.
2. In the Properties dialog box on the General tab, under Attributes select Read-only and click OK.
Working with the Gateway Locator Utility
The Gateway Locator utility provides control of and insight into any gateway configuration on your network. This topic explains how to use the utility for a variety of purposes.
The utility enables users to determine or change the Workgroup Engine used as the gateway for the data files in a particular directory. It is used only with the 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 in use and therefore locked, 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 or in ZenCC from the Tools menu.
Note:  The locator can be used to set the gateway for any data directory. Directory locations are not stored with the tool, so 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. The browse button allows you to find and select a new target directory.
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 the chosen directory, the box reads “unassigned.”
Changing the Gateway Workgroup Engine
After selecting a target directory, click Change to choose the Workgroup engine 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:
Enter or browse for the machine name you wish to serve as gateway.
Running the Workgroup Engine as a Service
By default, the Workgroup Engine is installed to run as a service for a fresh installation. 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 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 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 installation. See Installing Zen 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 Zen databases on another machine. "System Account" has no rights on other machines to Zen databases.
If you want the Zen 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 Zen Workgroup available locally on the other machine that can be used to access the databases instead. Access the properties for the Zen 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.
Last modified date: 10/31/2023