Objectivity/DB Administration : Administration Tasks : Specifying Objectivity/DB Files
2 
Specifying Objectivity/DB Files
Many administrative tasks require you to create or reference Objectivity/DB files. These include data files (system-database files, database files, and container files), journal files, and boot files.
This chapter provides important information about:
Filenames.
Access permissions.
Pathnames for local and remote files.
Filenames
System-Database File
The name of the system-database file consists of the federated database’s system name (fdSysName), with filename extension.fdb:
fdSysName.fdb
You specify the system name when you create the federated database. The system name must conform to your operating system’s naming rules for files.
You can change the name of a system-database file using the ChangeFd tool. (Do not simply rename the file in the file system.) Note that other filename extension are accepted, such as .fdb, .FDB, or .FDDB.
A federated database’s system name is also used in the name of the associated boot file; see Boot Files.
Database Files
Database filenames are generated automatically.
Generated filenames are of the form:
dbSysName.fdSysName.DB
where dbSysName is the system name of the database and fdSysName is the system name of the federated database.
Container Files
The filenames of any external containers are generated automatically.
Generated filenames are of the form:
dbId_contId.CONT
where dbId is the identifier of the containing database and contId is the container’s identifier.
Journal Files
You specify the location (host and directory) for journal files when you create a federated database or change its properties.
The names of journal files are always generated. They are of the form:
oo_fdSysName_1_hostName_processId_userName_sessionID.JNL
where
fdSysName
System name of the federated database.
hostName
Name of the client host on which the transaction is running.
processId
Process ID (pid) of the process in which the transaction occurs.
userName
Name of the user who started the process.
sessionID
Session ID of the thread in which the transaction occurs; sometimes followed by one or more letters.
For example: oo_testfd_1_machine12_12345_joe_1.JNL
Boot Files
The name of the boot file consists of the federated database’s system name (fdSysName), with filename extension.boot. For example:
fdSysName.boot
The system name must conform to your operating system’s naming rules for files, and must be between 1 and 127 characters long inclusive.
You can change the name of a boot file using the ChangeFd tool. (Do not simply rename the file in the file system.)
File and Directory Access Permissions
Access permissions are set on data files, journal files, and boot files when they are created by Objectivity/DB tools or applications. You should ensure that every user or group running a tool or application sets permissions as appropriate to give other users or groups the access they require.
At a minimum, these access permissions must be sufficient to enable Objectivity servers (the lock server and AMS) to read and write the Objectivity/DB files. Note that when an application uses AMS, the account running AMS establishes the ownership of any files created by the application. You typically create a special account for running AMS.
Specifying Remote and Local Files
Many Objectivity/DB administration tools and programming interfaces require that you specify the names of Objectivity/DB files. For example:
Administration tools that create or move a system database file or journal files allow you to specify the desired locations for these files.
Administration tools that operate on a federated database require you to specify a boot file to identify that federated database.
Administration tools and configuration settings that set up storage locations for new data files require you to specify these locations.
Some Objectivity/DB programming interfaces define functions that require you to specify a boot file to identify a federated database.
Host and Path Formats
When your Objectivity/DB system is distributed among multiple hosts, you may need to specify:
Remote files or directories, which are located on remote data-server hosts
Local files or directories, which are located on host where you are running the tool or application.
In general, a file or directory is specified as a pair of strings:
host
A TCP/IP network node name. In some cases, host may be a special string or omitted altogether, as described in the following subsections.
path
The relative or fully qualified path of the file or directory. The format of path may vary, as described in the following subsections.
You usually provide host and path strings to Objectivity/DB tools and configuration files according to the following conventions:
For a system-database file or a journal directory, you specify the host and path strings separately, as arguments to a pair of tool options.
For a bootFilePath or for a storage location for database files, you can specify the host and path as a single string in host format, where the host is separated from the pathname by two colons:
host::path
The following subsections describe conventions for specifying host and path values when designating files on the different kinds of data-server hosts.
Files on the Local Host
To designate a file that resides on the local host (the host where you are running the tool or application), you can specify host and pathname information as follows:
host
Omit this value (or optionally specify the local host’s TCP/IP network node name).
path
The relative or fully qualified path of the file in the format accepted by the local operating system.
When you specify a local path, omitting the host value is the same as specifying the name of the local host. (An exception to this rule is described in “If the Local Host is a Processor Cluster” below.)
Names that are stored in a boot file must be usable by every application that will consult that boot file, including applications running on remote client hosts. Take this into account when specifying files on Windows hosts, which allow files to have both local names (for example, c:\project\myFD) and network-visible names (for example, \\mach33\c\project\myFD). To make a local file visible to remote Windows clients, you must specify host and path values as described in Files on Windows Network Data-Server Hosts.
Note:On Windows hosts, you may not designate local Objectivity/DB files using mapped drive letters (for example, Z: mapped to c:\project\myFD).
If the Local Host is a Processor Cluster
A processor cluster is a group of multiple processors that share the same local disk. A common scenario is to regard these processors as interchangeable (as if they comprise a single logical client host), even if they have distinct host names. That is, you can run a tool or application on one processor in a cluster, and then, if that processor becomes unavailable or overloaded, run the tool or application on another processor in the same cluster; on either processor, the tool or application regards files on the shared disk as local files.
To designate a file on the shared local disk of a processor cluster, you specify host and pathname information (from a processor in the cluster) as follows:
host
The literal string oo_local_host. This string causes the tool or application to use the local client-host operating system to resolve the path.
path
The relative or fully qualified path of the file in the format accepted by the local operating system.
Specifying the literal string oo_local_host ensures that the host information for the file is not specific to any particular processor in the cluster. (If you omit the host value instead of specifying the literal string oo_local_host, the host value will be set to the name of the particular processor running the application or tool.)
Files on AMS Data-Server Hosts
To designate a file on a remote data-server host running AMS, you specify host and pathname information as follows:
host
The data-server host’s TCP/IP network node name.
path
The fully qualified path of the file on the specified host. The path is passed to AMS on that host. Because AMS passes the path to the specified host’s file system, you use pathnames that are local to that host—for example, on Windows:
c:\project\myFD
When specifying a file on a Windows host running AMS, you must use the locally understood pathname; do not use a UNC share name.
Files on AMS data-server hosts are available to database applications running on any kind of client host.
Files on NFS Data-Server Hosts
To designate a file on a remote data-server host running NFS, you specify host and pathname information as follows:
host
The data-server host’s TCP/IP network node name.
path
The fully qualified path of the file on the specified host. The path is passed to the NFS server on that host. The path must start with the name of the NFS-exported file system that contains the file—for example, on a UNIX platform where /usr is exported:
/usr/project1/myFD
Alternatively, you can specify host and pathnames as follows:
host
Omit this value
path
A locally understood NFS mount name for the file—for example:
/net/machine33/usr/project1/myFD
Objectivity/DB uses the local mount table to translate the mount name into a host-format name whose host is the remote host, and whose path is the file’s name on that host. The path is passed to the NFS server on the remote host.
Files on NFS data-server hosts are available to database applications running on any kind of client host.
Files on Special-Purpose UNIX Hosts
Some distributed Objectivity/DB systems include data-server hosts that are special-purpose storage devices. Because they are not general-purpose computers, such storage devices might not be running an NFS server that Objectivity/DB can work with directly. When a file is stored on such a storage device, a tool or application must bypass Objectivity/DB’s name processing, and instead use the client host’s operating system to connect to the device and access the file.
To designate a file on a remote special-purpose storage device, you specify host and pathname information as follows:
host
The literal string oo_local_host. This string causes the tool or application to use the local client-host operating system to resolve the path.
path
A locally understood NFS mount name for the file.
Files on Windows Network Data-Server Hosts
To designate a file on a remote Windows Network data-server host, where that file is shared through a common Universal Naming Convention (UNC) share name, you specify host and pathnames (from a Windows client host) as follows:
host
The literal string oo_local_host. This string causes the tool or application to use the local client-host operating system to resolve the path. If you specify any other string for host, it will be converted to oo_local_host automatically.
path
The fully qualified network path to the file—that is, a UNC share name for the file such as \\mach33\c\project\myFD.
Files on Windows Network data-server hosts are available only to database applications running on Windows client hosts.
Warning:Do not use UNC share names (for example, when creating a federated database) if the resulting files will be accessed by applications running on a UNIX, Linux, or Macintosh client host. You must use AMS (and the corresponding naming conventions) to make files available to applications on these client hosts.
Note:On Windows hosts, you may not designate remote Objectivity/DB files using mapped drive letters (for example, Z: mapped to c:\project\myFD).
   
Preserving Spaces in Pathnames
When you specify a path to a file or directory in which any component name contains spaces, be sure to enclose the path in double-quotation marks. This applies to all tools with options for specifying a path. For example, the following command moves the federated database’s system-database file to a directory called test dir:
objy ChangeFd -sysfilepath "/test dir/myFd.FDB" -bootFile myFd
The quotation marks are preserved in the corresponding boot-file entry:
ooFDDBFileName="/test dir/myFd.FDB"
Filename Case Sensitivity
Objectivity/DB is sensitive to case when verifying filenames for certain operations. Therefore, when specifying the name of a file to Objectivity/DB, you must be careful to use the case that was used when the file was created.
You must specify Objectivity/DB files using the original case even on Windows, which otherwise allows you to access files using any case combination. For example, Windows allows you to access a file created as HELLO using HELLO, Hello, or hello. However, if this is an Objectivity/DB file, you may only use HELLO.