Objectivity/DB Administration : Administration Tasks : Using a Lock Server
8 
Using a Lock Server
Objectivity/DB provides concurrent multiuser access to data. To ensure that data remains consistent, database access is controlled through locks granted by a lock server.
This chapter describes:
General information about lock servers.
Checking whether a lock server is running.
Starting and stopping a lock server.
Changing the lock-server host for a federated database.
Listing the locks that are currently managed by a lock server.
Changing the log directory for the lock server.
Changing the lock-server port.
Troubleshooting problems with the lock server.
About Lock Servers
A lock server manages concurrent access to persistent objects by granting or refusing locks to requesting transactions. When a transaction requests data from a federated database, Objectivity/DB locates the lock server that services the federated database and then contacts the lock server to obtain a lock on the requested data. The lock is granted only if it is compatible with existing locks. Obtaining a lock prevents multiple concurrent transactions from performing incompatible operations on the same data, whether these transactions belong to different applications or to different threads of the same application.
Locks
A lock server grants locks to transactions requesting data from a federated database. Locks prevent multiple concurrent transactions from performing incompatible operations on objects. Depending on the request, the lock server may grant the transaction a read lock, an update lock, or an exclusive lock for a requested object.
Read lock
When a transaction has a read lock for an object, other transactions can concurrently obtain read locks for that object.
If the read lock was obtained by a standard transaction, no other transaction can obtain an update lock for the object. If the read lock was obtained by a transaction that uses the multiple readers, one writer (MROW) concurrency mechanism, at most one other transaction can obtain an update lock.
Update lock
When a transaction has an update lock for an object, no other transactions can concurrently obtain an update lock for that object, although transactions using MROW may obtain read locks.
Exclusive lock
When a transaction has an exclusive lock for an object, no other transaction can concurrently obtain any kind of lock on the object. Objectivity/DB obtains exclusive locks for operations such as creating a container.
Locking a persistent object causes its container to be locked.
Read and update locks exist only while the lock server is running. If the lock server or its host fails during a transaction, any locks held by the transaction cease to exist. For information about recovering transactions in this situation, see Automatic Recovery From Lock-Server Failures and Manual Recovery From Lock-Server Host Failures.
Lock-Server Host
A lock server is identified by its location—that is, by the workstation, or lock-server host, on which it is running. Every federated database stores the name of a lock-server host as a property. When a transaction requests data from a federation, Objectivity/DB inspects the corresponding boot file to identify the relevant lock-server host, and then contacts the lock server running on that host.
A single lock server may service multiple federated databases. In this situation, each federated database specifies the same workstation as the lock-server host.
Because a federated database can have only one lock-server host, it can be serviced by only one lock server.
You can change the lock server that services a federated database; see Changing Lock-Server Hosts.
Lock Servers on the Network
You may run multiple lock servers on the same network, depending on the number of federated databases to be supported. A lock server may, but need not, run on the same workstation as the federated databases it serves.
Message Logging
A running lock server maintains a log of any messages it produces. The location of the logged messages depends on the operating system of the lock-server host.
Windows
On Windows, the lock server’s messages are available through the Windows Event Viewer, under Windows Logs > Applications.
UNIX, Linux, and Macintosh
On UNIX, Linux, and Macintosh, a lock server creates log files in a log directory on the lock-server host. By default, the log directory is located as follows:
On UNIX or Linux, the default log directory is /usr/spool/objy.
On Macintosh, the default log directory is /var/spool/objy.
You can set up a nondefault log directory at any time; see Changing the Log Directory.
Within the log directory, the lock server creates a file called oolsrec.log to record any errors produced if automatic recovery is triggered. This file is overwritten each time the lock server starts; older versions of the file append a number n to the filename.
You must run the lock server under an account that has read and write access to the log directory and to the files in it. You must not modify or delete log files. You should not move log files, except if you are changing the log directory.
Checking Whether a Lock Server is Running
A lock server is normally started automatically during product installation. You use an administration tool to check whether a lock server is running.
To check the status of a lock server on a particular workstation hostname:
Enter the following command at a command prompt:
objy CheckLs -host hostname 
Starting a Lock Server
During product installation, you typically configure a workstation to start a standard lock server automatically every time the machine reboots. However, there may be situations that require you to start (or restart) a lock-server process.
To manually start a lock server on the current host:
Enter the following command at a command prompt:
objy StartLockServer 
Note: On Windows, you must start the command prompt as administrator.
You enter the command with arguments if you want to enable automatic recovery.
You must start the lock server under a user account with sufficient access permissions to:
Read the boot file for each federated database to be serviced.
Read and write all data files and journal files to be serviced, as well as the directories containing them.
Read and write to the lock server’s log directory, if required; see Message Logging.
You can optionally configure your workstation to start the lock server whenever the machine reboots; see the installation and configuration documentation on the Objectivity Developer Network.
 
Stopping a Lock Server
You can stop a lock server at any time, provided that it is not currently servicing any active transactions. An active transaction is any transaction that holds a lock, even if the process that started it is no longer running. Thus, an active transaction may be currently in progress or waiting for recovery.
Note:If you stop a lock server while a database application is still running (for example, while the application is between transactions), the application will encounter an error the next time it tries to start a transaction.
To stop a lock server on a particular workstation hostname:
Enter the following command at a command prompt:
objy StopLockServer -hostName hostname 
If You Cannot Stop a Lock Server
A lock server cannot be stopped while servicing an active transaction. If an application is using a lock server that you want to stop, you:
1. Run LockMonitor to determine which transactions are currently using the lock server.
2. If necessary, use ListWait to determine which processes are using the lock server; notify the process owners to commit or abort their transactions.
3. If any locks belong to processes that are no longer running, use CleanupFd to recover the incomplete transactions.
4. When you are certain that no active transactions are using the lock server, terminate the lock-server process as you normally would on your platform.
Changing Lock-Server Hosts
You may need to change the lock server that services a federated database. For example, if the current lock-server host for a federated database has become permanently inaccessible, you must use a lock server on a different host. Or, to reduce the number of federated databases serviced by a particular lock server, you can assign some of them to a different lock server.
To change the lock-server host for a federated database:
1. Ensure that the new lock-server host has network access the journal directory and data files associated with the federated database, using the pathnames listed in the boot file and catalogs. (To view these pathnames, see Getting Federated-Database Information.)
2. Run ChangeFd with the -lockServerHost option and the -bootFile option. If the old lock server is not running, add the -standalone option.
You can now restart the lock server on the new lock-server host (see Starting a Lock Server).
Example UNIX
This command sets the new lock-server host for the federated database myFD to mach44 (assuming that the old lock server is still running):
objy ChangeFd -lockServerHost mach44 -bootFile myFD
 
Listing Current Locks
You can list all locks and processes currently managed by the lock server. To do this, use LockMonitor. You can use this information to determine the locking status on objects and to locate unexpected locks. If you find locks that are held by transactions belonging to terminated application processes, you can use CleanupFd to release them.
Changing the Log Directory
On UNIX, Linux, and Macintosh only, you can change the log directory for lock-server log files.
UNIX and Linux
Perform the following steps to change the lock server’s log directory from oldLogDir to newLogDir, where newLogDir could be either the default log directory usr/spool/objy or a nondefault log directory:
1. Log in as root.
2. Verify that the desired log directory exists, and, if necessary, create it. Enter:
mkdir newLogDir
3. Set the directory’s permissions to enable the lock server to create and update files in this directory, and to enable all users to read and write files there. Enter:
chmod 777 newLogDir
4. Arrange for the lock server to find newLogDir:
If newLogDir is the default log directory, you must unset the OO_SERVER_LOG_DIR environment variable.
If necessary, remove any command that sets this environment variable in a startup file (such as .login for the account on which you run the lock server).
If newLogDir is a nondefault log directory, you must set the OO_SERVER_LOG_DIR environment variable to newLogDir.
If necessary, add a command to set the environment variable in a startup file (such as .login for the account on which you run the lock server). If such a command already exists, edit it to set the environment variable to newLogDir.
5. Put these changes into effect:
a. Stop the lock server.
b. Move any existing logged files from the oldLogDir to newLogDir.
c. Start the lock server.
   
Changing the TCP/IP Port for the Lock Server
The lock server is assigned a default TCP/IP port number by Objectivity/DB. This port is used by remote processes (such as Objectivity/DB applications or AMS) for communicating with the lock server.
On rare occasions, you may be prevented from starting the lock server because another service is already using the default lock-server port. If possible, you should assign the other service to a different TCP/IP port. If you cannot do this, you can assign the lock server to a nondefault port; however, you will have to make this change on every host that runs a process that interacts with this lock server.
UNIX, Linux, and Macintosh
To assign a lock-server port:
1. Log in as root.
2. Add the following entry to the TCP/IP services file (typically, /etc/services):
ools-xx      portNumber/tcp     # Objectivity/DB lock server
where
xx
The current version of the lock server; contact Objectivity Customer Support to get the current version.
portNumber
TCP/IP port number (a number greater than 1024).
3. (UNIX only) Send a hangup signal to your inetd process. For example, if inetdPid is the process identifier for the inetd process, enter:
kill -HUP inetdPid
Note: You must make this change on every host that runs the lock server or a process that uses the lock server (an Objectivity/DB application or AMS).
If you are using the Network Information Service (NIS), you should ask your system administrator to perform the equivalent operation for your NIS configuration.
Troubleshooting Problems With the Lock Server
Because lock servers control distributed systems, problems with lock servers may differ across operating systems.
All Platforms
Lock-Server Timeout
By default, an application or tool waits 25 seconds for the lock server to respond to a request. However, a lock server running on a busy machine may need more time to respond. If an application or tool consistently signals a lock-server timeout error you can increase the network timeout period by setting the OO_RPC_TIMEOUT environment variable to the desired number of seconds—for example:
 
set OO_RPC_TIMEOUT=10
(Windows)
setenv OO_RPC_TIMEOUT 50
(UNIX)
export OO_RPC_TIMEOUT=50
(Macintosh)
Alternatively, you can consider running the lock server on a less congested host.
The value of the OO_RPC_TIMEOUT environment variable overrides any network timeout period set by an application. For information about setting a network timeout period in an application, see the documentation for the appropriate Objectivity/DB programming interface.
Note:On Windows, the operating system limits the network timeout period to 20 seconds, even if you set a higher value for the OO_RPC_TIMEOUT environment variable.
Lock-Server Connection Failure
If an application or tool signals a failure to connect to a lock server, and you know the lock server is running, the connection failure may be due to a heavily loaded network. You can increase the likelihood that a connection will be made by increasing the number of attempted connections. To do this, you set the OO_CONNECT_RETRIES environment variable to be the desired number of additional attempts to be made after an unsuccessful initial attempt—for example:
 
set OO_CONNECT_RETRIES=4
(Windows)
setenv OO_CONNECT_RETRIES 2
(UNIX)
export OO_CONNECT_RETRIES=2
(Macintosh)
The value of this environment variable overrides the system default, which is:
0 on UNIX and Macintosh; only a single attempt is made (the initial attempt and no retries).
2 on Windows; a total of three attempts are made (an initial attempt, plus two retries).
The value of the OO_CONNECT_RETRIES environment variable is overridden by any value set by an application. For information about setting the number of connect retries in an application, see the documentation for the appropriate Objectivity/DB programming interface.
Windows
Consider the following information if you encounter problems with the lock server on a Windows platform. You can use the Windows EventViewer to check the Application log (or Applications and Services Logs) for any relevant messages.
If You Cannot Start a Lock Server
If you cannot start a lock server on a Windows platform, it may be due to one of the following reasons:
Required services have not initialized.
When Windows starts or reboots, many services required by the lock server are initialized, including TCP/IP. It is possible for initialization to take time. If the lock server fails to start immediately after the system reboots, try starting it again after a minute or so.
TCP/IP is not installed.
The lock server requires that a Winsock-compatible TCP/IP stack is installed and correctly configured. See “TCP/IP Configuration Problems” below for more information.
A port conflict exists between the lock server and another running process.
If You Cannot Connect to the Lock Server
If your applications cannot connect to the lock server in a Windows environment, it may be due to one of the following:
Lock server is not running.
Make sure the lock server is running on the machine specified by your boot file.
TCP/IP is not installed.
Objectivity/DB applications require that a Winsock-compatible TCP/IP stack be installed and correctly configured. See “TCP/IP Configuration Problems” below for more information.
Different hosts have different TCP/IP ports assigned to the lock server.
TCP/IP Configuration Problems
Objectivity/DB applications require that a Winsock-compatible TCP/IP stack be installed and correctly configured. In particular:
The TCP/IP hosts configuration file should contain entries for your workstation and any other machines you wish to access, even if you are using DNS. Entries should include the hostname and IP address.
If you are using DHCP, your system administrator should set up a DHCP reservation for your host to ensure that the same IP address will always be assigned to your host.
Note:The TCP/IP hosts configuration file is typically %systemroot%\system32\drivers\etc\hosts.
Some common TCP/IP configuration problems are listed below. You should consult your system administrator before changing your TCP/IP configuration:
Incorrect IP address or hostname is specified.
Make sure that the IP addresses and hostnames of all the machines are consistent on all hosts. This may involve checking each workstation’s TCP/IP hosts configuration file, verifying that DNS is configured properly, or verifying that DHCP is configured properly.
Hostname is missing.
Make sure that an entry for your workstation is included in the TCP/IP hosts configuration file.
UNIX, Linux, and Macintosh
Consider the following information if you encounter problems with the lock server on a UNIX, Linux, or Macintosh platform. You can check the system log file for any relevant messages.
If You Cannot Start the Lock Server
A port conflict may exist between the lock server and another running process.
If You Cannot Connect to the Lock Server
If an application or tool signals a failure to connect to a lock server, and you know the lock server is running, the lock server may have obtained too many file descriptors and reached the per-process limit set by the operating system.
A lock server obtains one file descriptor for each session that has started a transaction, and the lock server has a one-time overhead of up to seven file descriptors. Consequently, the total number of file descriptors obtained by the running lock server process is the sum of the one-time overhead and the file descriptors obtained on behalf of each accessing application. If the total is greater than the limit for your operating system, you can work around the problem by increasing the operating system’s file-descriptor limit, or decreasing the number of accessing applications.
File Access Requirements
To start a lock server, you must have read and write access to its log directory or the required files in it. See Message Logging.
Files Not Exported by NFS
The lock server requires that any user directories that contain, or will contain, Objectivity/DB files be exported by NFS. If they are not exported, refer to the documentation for your operating system to export these directories. To export these directories, place them in the /etc/exports file.