Objectivity/DB Administration : Administration Tasks : Advanced Multithreaded Server
Advanced Multithreaded Server
In a distributed system, an Objectivity/DB application may request data that is local (on the same host as the application) or remote (on a different host). When servicing a request for remote data, Objectivity/DB contacts data-server software to obtain that data. If you choose, you can use Objectivity’s Advanced Multithreaded Server (AMS) as your data-server software.
This chapter describes:
General information about AMS.
Deciding whether to use AMS.
Checking whether AMS is running.
Starting and stopping AMS.
Changing the AMS port.
Troubleshooting problems with AMS.
About AMS
AMS is data-server software that is provided with Objectivity/DB. You can run AMS on remote data-server hosts to make the data files or journal files on those hosts available to Objectivity/DB applications. AMS is an optional alternative to native file servers (commonly, NFS or Microsoft Windows Network), which means you can use AMS on any or all remote data-server hosts in a distributed Objectivity/DB system.
When you use AMS, you refer to each Objectivity/DB file by specifying the data-server host on which the file resides and the pathname of the file on that host (for more information, see Files on AMS Data-Server Hosts). You do not need to export any file systems or use special network share names or mount names.
You can run AMS on multiple hosts in a network. On a single workstation, however, you may run only one AMS process per version of AMS.
Deciding Whether to Use AMS
In most cases, AMS is recommended over NFS or Microsoft Windows Network because of performance advantages, flexibility, and ease of use.
You should run AMS on a data-server host if:
Your Objectivity/DB application performs many update transactions, or modifies or creates many objects per update transaction.
Your Objectivity/DB application performs a moderate number of update transactions and is connected to the server host via a WAN or large LAN.
The data-server host is a node in a Spark cluster in which you are running a Spark driver application.
NFS is not already in use on the data-server host.
You prefer not to export complete NFS file systems to all users.
You prefer not to run NFS.
You need interoperability between platforms. Although you can use other networking software, AMS offers a simpler solution.
Checking Whether AMS is Running
AMS may, but need not be, started automatically during product installation. You use an administration tool to check whether a AMS is running.
To check the status of AMS on a particular workstation hostname:
Enter the following command at a command prompt:
objy CheckAms hostname 
Starting AMS
You typically start AMS on every host that provides storage for one or more data files. On a given host, you can run only one AMS process per version of AMS.
To manually start AMS on the current host:
Enter the following command at a command prompt:
objy StartAms 
Note: On Windows, you must start the command prompt as administrator.
You must start AMS under a user account with sufficient access permissions to:
Read and write all data files and journal files to be accessed, as well as the directories containing them.
Create new data files and journal files wherever necessary.
For security reasons, you should set up an account for a special-purpose user or group with just the minimum necessary access permissions. On UNIX, Linux, and Macintosh, It is strongly recommended that you not run AMS under the root account.
You can optionally configure your workstation to start AMS whenever the machine reboots; see the installation and configuration documentation on the Objectivity Developer Network.
Stopping AMS
You can stop AMS if no database applications are currently using it. An error message is displayed if you try to stop AMS while database applications are using it.
To stop AMS on a particular workstation hostname:
Enter the following command at a command prompt:
objy StopAms -hostName hostname 
Changing the TCP/IP Port for AMS
AMS is assigned a default TCP/IP port number by Objectivity/DB. This port is used by remote processes (such as Objectivity/DB applications) for communicating with AMS.
On rare occasions, you may be prevented from starting AMS because another service is already using the default AMS port. If possible, you should assign the other service to a different TCP/IP port. If you cannot do this, you can assign AMS to a nondefault port; however, you will have to make this change on every host that runs a process that interacts with AMS.
UNIX and Macintosh
To assign a TCP/IP port for AMS:
1. Log in as root.
2. Add the following entry to the TCP/IP services file (typically, /etc/services):
ooams-xx      portNumber/tcp       # Objectivity/DB AMS
The current version of AMS; contact Objectivity Customer Support to get the current version.
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 either AMS or a process that uses it (an Objectivity/DB application, a lock server, or Objectivity/DB tools).
If you are using the Network Information Service (NIS), ask your system administrator to perform the equivalent operation for your NIS configuration.
Troubleshooting Problems With AMS
All Platforms
AMS Timeout
By default, an application or tool waits 25 seconds for AMS to respond to a request. However, when running on a busy machine, AMS may need more time to respond. If an application or tool consistently signals an AMS 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:
setenv OO_RPC_TIMEOUT 50
export OO_RPC_TIMEOUT=50
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.
AMS Connection Failure
If an application or tool signals a failure to connect to AMS, and you know AMS 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:
The value of this environment variable overrides the system default, which is:
0 on UNIX or 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.
UNIX, Linux, and Macintosh
AMS Cannot Open More Files
Each time AMS services a request for a data file or a journal file, AMS obtains two file descriptors—one for the accessed file and one for a connection socket. AMS keeps these file descriptors as long as the accessed file remains open. Under some circumstances, AMS may accumulate enough file descriptors to reach the per-process limit set by the operating system. When this happens, AMS reports an error the next time a file is requested.
AMS generally accumulates too many file descriptors when multiple concurrent, highly multithreaded applications all request data from the same data-server host. Each requesting thread contacts AMS on that host using a particular session (a portion of an application that manages a sequence of transactions). Every session has a limit on the number of files it can request; if a session tries to request more than the specified number of files, Objectivity/DB must close one file (for example, a database file) before it can open another one. Each application sets the file-descriptor limit for its sessions, as described in the documentation for your Objectivity/DB programming interface.
Accordingly, particular AMS process obtains the following number of file descriptors on behalf of a particular application:
numSessions x numFiles x 2
Number of sessions contacting the AMS process
Maximum number of file descriptors allowed by the application for each session
The total number of file descriptors obtained by a particular AMS process is the sum of the file descriptors obtained on behalf of each accessing application. If the total is greater than the limit for your operating system, an administrator can consider the following workarounds:
Increasing the operating system’s file-descriptor limit.
Reducing the file-descriptor usage of each individual AMS process by distributing files among more data-server hosts running AMS.