Foreign Directories

Each Zim database has its own object dictionary. All objects (i.e. entity sets, forms, variables, and so on) that are described in the object dictionary are created in a Zim directory. Normally, an application developer creates the Zim directories that are used within one particular database. A foreign directory, on the other hand, is a Zim directory that is defined by one database, but is used by other databases. By accessing a foreign directory, you gain access to all objects created in that directory.

Why Use a Foreign Directory?

There are many situations in which a foreign directory can be useful. One common example is the toolbox, a database containing application programs that are useful in, and therefore shared among, many different databases.

For example, while developing an application, you might have created a directory containing utility programs. These utilities could be useful in other situations, but you do not want to re-create them for each new database. By following the procedures described below, the utility directory can be defined as foreign in the other databases. The directory can then be used in databases other than the one in which it was created.

How Foreign Directories are Used

The procedure described below is an overview of how foreign directories are used. The remainder of this section describes this in more detail.

In general, the use of a directory from one database (the host database) within another database (the connecting database) involves five steps:

1. In the Object Dictionary of the host database, define the target directory, including a special directory ID number. Create the directory, using the CREATE command.
2. In the Object Dictionary of the connecting database, define the target directory again. This definition should be identical to that in the host database, except that the directory should be defined as foreign.
3. In the connecting database, create the directory, using the CREATE command.
4. At the operating system level, switch to the operating system directory that contains the connecting database. Use your text editor to edit the foreign directories file (called dirs.zim), adding an entry that gives the location of the foreign directory within the file system. You can also use the "Update Dirs.Zim" button on the Directories window in DC to edit the file directly.
5. Return to Zim and the connecting database. Use the ACCESS command to access the foreign directory.

Note: A connecting database can access many foreign directories simultaneously, provided each directory has a unique directory ID number (dirID). A single directory can be accessed as a foreign directory simultaneously by many databases.

Note2: If a single ZimServer manages different databases and at least one of them has foreign directories, all directories, local or foreign, must have unique dirID across all databases.

Defining a Foreign Dictionary - Detailed Description

A foreign directory consists of two components. The first component is the original directory created in the host database. It is this directory that is accessed by users of other databases. The second component is a directory that is created as foreign in the connecting database.

In the host database

If a particular directory is to be used from within other databases, the directory must be created in the host database, using the procedure described below. The directory is created essentially in the normal way; however, it must be assigned a special directory ID number.

1. Add a record to EntitySet Directories in the Object Dictionary. This record must set

• • DirName to the name of the directory
  • DirId to the directory ID number. This number should be between 1 and 240. The DirId should not conflict with the DirId of any other directory to which a user might connect at the same time.
  • Foreign to NO

2. Create the directory in the normal manner, using the CREATE command. If the foreign directories (dirs.zim) file belonging to the host database contains an entry that matches this directory's DirId, then the operating system file that corresponds to this directory is relocated to that entry.

Note: The root directory (namely Zim) cannot be used as a foreign directory. You should ensure that the directory to be used in other databases is a sub-directory.

In the Connecting database

To enable users of another database to connect to an existing (foreign) directory, continue the above procedure with the following steps:

1. In the connecting database, add a record to entity set Directories in the Object Dictionary. This record must set

• • DirName to the name of the foreign directory
  • DirId to the directory ID of the foreign directory
  • Foreign to YES

2. Create the directory in the normal manner. Because the Foreign field in the Directories record has been set to Yes, no files are created for this new directory.

Note: The DirName and DirId of the foreign directory must be the same as the DirName and DirId in the host database.  

At the Operating System level

Before a user of the connecting database can employ the ACCESS command to connect to a foreign directory, the connecting database must contain a foreign directories (dirs.zim) file with an entry describing the location of each foreign directory. To create this file, use a text editor at the operating system level. The file should be stored in the operating system directory that contains the connecting database.

Each entry in the foreign directories file has the format:

dirid file# path

where

dirid is the dirid of the foreign directory

file# is the number of the file that corresponds to the directory in the host database (i.e. nnnn to zimnnnn). To determine the file#, run the ZIMFILES utility against the host database or use the command

output $filename (directory-name)

For example, the entry

11 126 \usr\tools

means that the directory whose dirid is 11 can be found in the file \usr\tools\zim0126.

Accessing a Foreign Directory

Once a foreign directory has been defined and created in the host and connecting databases, and the foreign directories file exists with the appropriate entry, the foreign directory is accessible from within the connecting database. To access the foreign directory, use the following procedure:

1. Invoke Zim in the connecting database.
2. Use the ACCESS command to access the foreign directory by name, as shown in the following example:

access Utilities read

All objects defined in the foreign directory are now available from within the connecting database.

Note: Foreign directories can be accessed only in read mode.

The Location of Files Associated with a Foreign Directory

The dirs.zim file specifies the location of the operating system (OS) file that corresponds to the foreign directory. But where does the system look for the files that correspond to the entity sets, relationships, programs and so on that are defined in the foreign directory?

By default, Zim looks for these files in the path specified in the dirs.zim file for the foreign directory file itself. It is possible, however, to distribute these files to other parts of the file system by using an areas file with special document file names in the host database. The procedure for using an areas file in a host database is exactly as described for independent databases in Distributing Database Files.

An areas file for a foreign directory can distribute some or all of the associated database files (i.e. EntitySets, relationships, compiled programs, and so on). Documents defined in a foreign directory can use the special file name prefixes - including the double quotation mark and the right parenthesis - to locate associated files in the database directory and work directory belonging to the connecting user.

Example

To illustrate, let's look at a Utilities example. Consider the following background information:

• The directory Utilities in the host database is defined in the operating system directory D:\UTILPROG. The directory ID for Utilities is 30.
• In directory Utilities, three documents are defined as shown below:

>list all docs

Docname        FileName       DirName

DictReport     dict.rep       Utilities
ReportOut      )report.out    Utilities
UserLog        "user.log      Utilities

• In directory Utilities, two entity sets are also defined as shown below:

UtilEnt1 (stored in operating system file ZIM0129)
UtilEnt2 (stored in operating system file ZIM0130)

• The host database has an associated file that is located, with directory Utilities, in operating system directory D:\UTILPROG. The areas file contains the entry

129 C:\UTZIM

• The connecting database has an associated foreign directories file that contains the entry

30 117 D:\UTILPROG

• The connecting user's work directory is C:\APPLDIR\USER1.

Given this situation, the connecting and host databases both contain an areas file that relocates the files associated with entity sets. In the connecting database, a foreign directories file establishes D:\UTILPROG as the default location for all files associated with objects in the foreign directory Utilities. The foreign object ReportOut (a document) is defined as being located in the connecting user's work directory; similarly, UserLog is defined as being located in the connecting user's database directory.

Accessing Foreign EntitySets

By connecting to a foreign directory, you gain access to the data in the EntitySets and relationships with fields that are defined in that directory.

To obtain read/write access to foreign database fields, you can declare those files as non-shared in the areas file associated with the host database. For example, to obtain read/write access to a foreign EntitySet called UtilEnt whose corresponding operating system file has the name ZIM0185, you would place the entry

185  D:\UTILPROG       % This is a Zim on Windows example.
185 /usr3/utilprog/    % This is a Zim on UNIX example.

in the areas file associated with the host database.

In Zim 8, foreign databases can be read or written as any normal database.

Limitations on Foreign Directories

The following limitations apply to the user of foreign directories:

1. Each directory accessed by an application must have a directory ID unique among all directories being accessed at the same time. Directories, in this case, include sub-directories of foreign directories.
2. One database cannot connect to the root directory (Zim directory) of another database (i.e. the root directory cannot be a foreign directory).
3. A foreign directory cannot be updated using the COMPILE, UNCOMPILE, CREATE, ERASE, PERMISSION, or RENAME command. You cannot update the definition of objects defined in a foreign directory.
4. A connecting database cannot connect to foreign directories defined within the foreign directory of the host database.
5. Foreign database files that have been encrypted with an ENCRYPT command can be accessed from a connecting database only if the connecting and host databases were both initialized using the same encryption key. The encryption key is specified when the ZIMINIT utility is executed to initialize a new Object Dictionary.